Remove use of ANSIBLE_METADATA in collection modules

[samccann]

SUMMARY

ANSIBLE_METADATA has two fields of use:

• supported_by - this field is no longer relevant as the collection itself is either certified or not.
• status - deprecated and removed are covered in the collectionsmeta/routing.yml

That leaves status of preview vs stable. Do collection owners still see relevance in that information per module? If so, let's create a DOCUMENTATION field to cover that.

ISSUE TYPE

• Bug Report

[felixfontein]

I think this field would be useful as an optional DOCUMENTATION field (default value would be preview).

[abenokraitis]

preview vs. stable wasn't consistently used, nor enforced and therefore I would say it isn't needed. For example, I see ios_config as showing preview per: https://docs.ansible.com/ansible/latest/modules/ios_config_module.html#ios-config-module and doesn't really mean anything at this point.

[cidrblock]

As an alternative, could we possibly state moving forward it is a freeform dictionary of key value pairs of depth 1, the use would be left up to the module developer to add any metadata they might need. From a documentation standpoint, we would either need to ignore it entirely as the fields would not be guaranteed consistent, or simply render it as a two column table.

[jillr]

I'm not a fan of making it a freeform dictionary. This could lead to some collections making liberal use of ANSIBLE_METADATA for information that might belong elsewhere in docs, and giving users an inconsistent experience with collections.

I'm with felixfontein here, make preview/stable a DOCUMENTATION field. I'd lean slightly towards making the default stable though - if we're confident enough to merge and release the code it should be stable unless we have an explicit, intentional reason to release something as a preview.

[felixfontein]

@jillr I disagree about the default: often modules need contact with users for some time to find out whether the interface is really working as intended and useful (there might be important use-cases nobody during the review process thought about, which are crippled by the interface). Declaring it stable by default means that everyone has to remember to explicitly set it to preview once a new module is created, or that stable will loose its meaning as module interfaces will be changed nonetheless.

[resmo]

+1 for documentation field, default=preview (consistent with 2.9 behaviour).

It would also be easy to change the default to stable in the plugin doc_fragment and overwrite in the modules to preview where appropriate.

[cidrblock]

@jillr makes a good point here. Rather than change it's intended use, eliminate it all together and let the developer add metadata they need in some other manner. WRT status, collections will be using semver which can indicate changes to argspec/behavior over time. I don't see a need for it moving forward.

[jillr]

@felixfontein It's a very slight preference, and it does put more expectation on the collection maintainer before merging. I'm happy to go with either way that the majority of folks prefer, which looks to be preview.

[samccann]

Related issue on ansible/ansible- ansible/ansible#69454

[samccann]

An update on this - ansible-base is removing the need for ANSIBLE_METADATA (see ansible/ansible#69454). We won't at this time replace this with a documentation field, but please continue the discussion as needed on this proposal - ansible/proposals#68

[gundalow]

I approve of the deletion of ANSIBLE_METADATA from ansible-base and Collections.

I don't currently see any need to add any type of marker for tech-preview vs stable.

[Andersson007]

will sanity tests fail when they find ANSIBLE_METADATA ?
it can come again with new modules which have PRs but are not merged yet

[felixfontein]

Right now they don't. They might do that in the future though.