Cannot deprecate a collection plugin

[charlesrocket (-k)]

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 modules → action 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/remote_vars.py:0:0: deprecation-mismatch: "meta/runtime.yml" and DOCUMENTATION.deprecation do not agree.
ERROR: plugins/modules/remote_vars.py:0:0: 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'}

[mariolenz]

It looks like there are two remote_vars.py. If you change modules → action, I guess you should add the deprecation to plugins/action/remote_vars.py.

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

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

[charlesrocket (-k)]

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)

[felixfontein]

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.

[charlesrocket (-k)]

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

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

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

[charlesrocket (-k)]

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

[charlesrocket (-k)]

I just got all tests green

/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

ci: fix `docsite`

[flowerysong]

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.

[charlesrocket (-k)]

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

[felixfontein]

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

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

[felixfontein]

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.

[charlesrocket (-k)]

Thanks! I’ve been looking for this one