How-to deprecate X - Documentation to be added, but where?

russoz · January 5, 2025, 12:07am

Hi everyone,

Being a maintainer for community.general for a while means I have had to deal with a number of different situations. It is a lot of different things we need to remember and, honestly, I cannot keep all of them in mind. One of those things is deprecating stuff, and then all the different ways to deprecate stuff, depending on what stuff is. So, I wrote this document to be my cheatsheet:

github.com

russoz-ansible/ansible-contrib-unofficial/blob/main/deprecations.md

Deprecations
============

Given the standing policies for backwards compatibility, any change on existing elements of Ansible (core or a collection) must go through a deprecation period. Different elements in Ansible have distinct strategies for being deprecated. This document tries to consolidate that, so it can be consulted as a handy reference on the topic.

## Deprecating a module or plugin

Deprecating modules is clearly and concisely documented in the official Ansible documentation:

* [Deprecating modules and plugins in the Ansible main repository](https://docs.ansible.com/ansible/latest/dev_guide/module_lifecycle.html#deprecating-modules-and-plugins-in-the-ansible-main-repository)
* [Deprecating modules and plugins in a collection](https://docs.ansible.com/ansible/latest/dev_guide/module_lifecycle.html#deprecating-modules-and-plugins-in-a-collection)

## Deprecating a parameter

Use the following steps:

* Add the attributes `removed_in_version` and `removed_from_collection` to the parameter. Example:
  ```python
  argument_specs=dict(
      # ...

This file has been truncated. show original

Recently, a question came up in one of the collection’s issues on how to deprecate the current default value of a parameter, which is one of the cases covered in the deprecations doc, so I posted the link there and it was suggested (by @felixfontein) that it could be added to the main Ansible docs. Great idea!

@samccann suggested that it could be added to the end of https://docs.ansible.com/ansible/latest/dev_guide/module_lifecycle.html , however as I was starting to actually get it done, I gave it a second look and it does not look like the deprecations document has much to do with module lifecycle.

I am raising this topic to bring in suggestions and/or other perspectives on the issue. Where should that piece of documentation go?

samccann · January 14, 2025, 5:10pm

@russoz We chatted about this in the DaWGs meeting the the recommendation is for you to add a new page to the developer guide for this. Thanks!

Topic		Replies	Views
Cannot deprecate a collection plugin Get Help collections , documentation	12	228	January 6, 2024
Renaming collections that are part of the Ansible community package Project Discussions collections , community-wg , rename	8	177	September 25, 2024
Deprecating pararmeters Ansible Project	1	1	June 25, 2014
Managing documentation versions Ansible Project	5	0	April 13, 2013
Collection module documentation available now on docs.ansible.com for review Ansible Developer galaxy-ng	0	0	July 27, 2020

How-to deprecate X - Documentation to be added, but where?

Related topics