Cannot deprecate a collection plugin

I tried to deprecate a collection following current docs but sanity tests are red with Documentation.deprecated not agreeing: fix: update plugin deprecation · charlesrocket/essential-collection@293a950 · GitHub

I wanted to deprecated on 1.4.0 but 2.0.0 also throwing Documentation.deprecated errors (not agreeing, extra fields).

According to docs I just need to change modulesaction in the deprecated meta declaration and reflect it in plugin docs but:

ERROR: Found 2 validate-modules issue(s) which need to be resolved:
ERROR: plugins/modules/ deprecation-mismatch: "meta/runtime.yml" and DOCUMENTATION.deprecation do not agree.
ERROR: plugins/modules/ invalid-documentation: DOCUMENTATION.deprecated: extra keys not allowed @ data['deprecated']. Got {'removed_in': '1.4.0', 'alternative': 'Use M(charlesrocket.essential.fetch_vars) instead.', 'removed_from_collection': 'charlesrocket.essential'}

It looks like there are two If you change modulesaction, I guess you should add the deprecation to plugins/action/

If you really want to deprecate plugins/modules/, then modules looks right to me.

I’m not sure, this is just an educated guess :wink:

1 Like

One is the actual plugin and another is just docs and is the only place besides meta/ where I should place deprecation entries, according to docs The lifecycle of an Ansible module or plugin — Ansible Documentation

the whole layout of action plugins is still a mystery to me)

You probably need to deprecate both the module file (which probably only contains docs in your case) and the action plugin in meta/runtime.yml.

1 Like

Wasn’t sure if I should merge into a single plugin file or deprecate docs as well (sounds silly) but I feel like I am getting somewhere with this double deprecation :joy_cat:

and once again, docs are clearly stating that why is optional:

ERROR: plugins/modules/ invalid-documentation: DOCUMENTATION.deprecated.why: required key not provided @ data['deprecated']['why']. Got None

Yep, duplicating deprecated meta entry got sanity tests green! Thanks

I just got all tests green :exploding_head::face_with_symbols_over_mouth::exploding_head:

/home/runner/work/essential-collection/essential-collection/docs/collections/charlesrocket/essential/remote_vars_module.rst:65: WARNING: undefined label: 'ansible_collections.charlesrocket.essential.fetch_vars_module'

this just makes zero sense. am i not able to put a role as an alternative to a module??? fetch_vars is a role: charlesrocket.essential.fetch_vars role – Includes variables from remote files — charlesrocket.essential Ansible collection documentation

Roles and modules fulfill very different needs so I wouldn’t be surprised if no one anticipated someone wanting to point to an alternative that was not of the same type.

The issue was M(role) in the module’s documentation. Tried with “R” when failed to find any docs on role deprecation — tests are green (?) but docsite outputs an error instead of the string. Going with the code attribute then :face_with_head_bandage:

Well, M(...) refers to a module, so it’s not surprising that it complains if you put the name of a role in there :slight_smile: (Module format and documentation — Ansible Documentation)

Better use P(...), which can reference modules, plugins, and roles: P(charlesrocket.essential.fetch_vars#role).


I created Improve module developing documenation for deprecation and linking by felixfontein · Pull Request #943 · ansible/ansible-documentation · GitHub to improve the documentation with the issues mentioned above.


Thanks! I’ve been looking for this one :sweat_smile:

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.