ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-04-25 03:41:25 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Module deprecation: docs, scheme and tests (#34100)

Browse source 
Enforce module deprecation.
After module has reached the end of it's deprecation cycle we will replace it with a docs stub.

* Replace deprecated modules with docs-only sub
* Use of deprecated past deprecation cycle gives meaningful message (see examples below)
* Enforce documentation.deprecation dict via `schema.py`
* Update `ansible-doc` and web docs to display documentation.deprecation
* Document that structure in `dev_guide`
* Ensure that all modules starting with `_` have a `deprecation:` block
* Ensure `deprecation:` block is only used on modules that start with `_`
* `removed_in` A string which represents when this module needs **deleting**
* CHANGELOG.md and porting_guide_2.5.rst list removed modules as well as alternatives
* CHANGELOG.md links to porting guide index

To ensure that meaningful messages are given to the user if they try to use a module at the end of it's deprecation cycle we enforce the module to contain:
```python
if __name__ == '__main__':
    removed_module()
```
This commit is contained in:
John R Barker 2018-01-30 12:23:52 +00:00 • committed by GitHub
parent 7c83f006c0
commit a23c95023b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
66 changed files with 241 additions and 4438 deletions
Download patch file Download diff file Expand all files Collapse all files

14
docs/docsite/rst/dev_guide/developing_modules_documenting.rst
View file

@ -201,9 +201,17 @@ The following fields can be used and are all required unless specified otherwise
:author:
Name of the module author in the form ``First Last (@GitHubID)``. Use a multi-line list if there is more than one author.
:deprecated:
If this module is deprecated, detail when that happened, and what to use instead, e.g.
`Deprecated in 2.3. Use M(whatmoduletouseinstead) instead.`
Ensure `CHANGELOG.md` is updated to reflect this.
If a module is deprecated it must be:
* Mentioned in ``CHANGELOG``
* Referenced in the ``porting_guide_x.y.rst``
* File should be renamed to start with an ``_``
* ``ANSIBLE_METADATA`` must contain ``status: ['deprecated']``
* Following values must be set:
:removed_in: A `string`, such as ``"2.9"``, which represents the version of Ansible this module will replaced with docs only module stub.
:why: Optional string that used to detail why this has been removed.
:alternative: Inform users they should do instead, i.e. ``Use M(whatmoduletouseinstead) instead.``.
:options:
One per module argument: