Deprecation in Collections and Ansible 2.10+

deprecation-in-collections.md

The collection name used in ansible/ansible is ansible.builtin.

1. Module/plugin deprecation:
   • deprecated entry in DOCUMENTATION with:
     • why, alternative (required)
     • either removed_in: <version> or removed_at_date: <date>
     • (removed_from_collection is automatically inserted if not present)
   • deprecation entry in meta/runtime.yml with:
     • warning_text (optional)
     • either removal_version: <version> or removal_date: <date>
2. Plugin option deprecation in DOCUMENTATION (for option itself, for ini entry, for vars entry, for env entry)
   • why (required)
   • alternatives (optional)
   • either version: <version> or date: <date>
   • (collection_name is automatically inserted if not present)
3. Module argument spec option deprecation:
   • either removed_in_version="<version>" or removed_at_date="<date>"
   • removed_from_collection="<namespace.name>" (required)
4. Module argument spec alias deprecation:
   • name="<alias>" (required)
   • collection_name="<namespace.name>" (required)
   • either version="<version>" or date="<date>"
5. Display.deprecated() and AnsibleModule.deprecate() calls
   • first positional argument msg (required)
   • either version="<version>" or date="<date>"
   • collection_name="<namespace.name>" (required)

Update: the field in top-level deprecated is called removed_from_collection, not collection_name. (It is auto-inserted, so this should affect anyone.)

Update: in point 2, the key is called alternatives, not alternative.