The main issue is that using this facility, which mirrors the existing one, is not backwards compatible and will result in an error when viewing the docs that use this. Mainly because ‘return’ had a simpler structure so it mixes with the fields and, which are equivalent to options but at the top level.
Note that B) has another con: if you mix return fragments with documentation in the module, like showing a version_added for a return value from a return fragment in RETURN, then it will result in documentation you cannot look at with ansible-doc. (Unless such ‘merges’ also have to be moved to RETURN_FRAGMENTS, which then means that return values can be specified both in RETURN and RETURN_FRAGMENTS, which in turn opens more cans of worms…)
Regarding punting / E and backporting / A: I’d prefer to have this feature in as early as possible, so we can start using it sooner. Depending on how it goes (i.e. if older ansible-doc versions cannot show docs, or show only incomplete docs), it will take some years until collections dropped support for all ansible-core versions that cannot handle return fragments and can start using that feature. It would be nice to reduce this amount of years to a very small number (preferably 0, which is quite unlikely though ).
As per B) the new variable can have diff sections, 1 for fragment list, 1 for overrides, any reimplementation should take these things into account. And, yes, this opens to duplication, one reason i’m not sure this is a good option.
As long as the warning is shown, users know that the documentation isn’t complete, but they can at least view the remainder of the docs. I would display the warning in the rendered text docs as well, though (maybe in the return value doc section), so that the warning is harder to miss.
I think it’s mostly a bugfix, since it prevents a crash. The warning part can be seen as a feature, but I personally think that it is OK since it’s a big help for users, which would otherwise not know that something is amiss and was ignored. (I tried the current warning, it’s basically impossible to see it without scrolling up after exiting the help viewer.)
With the caveat of - we’re not deeply considering coding and backporting considerations, We discussed in the DaWGs meeting today and in general are liking the direction of the E) proposal above. To be sure we are understing this, we think it means:
Feature works full in core 2.20 and above. Any user with that version and a collection with the new fragment time is in happy land.
For any older versions of core (TBD how far back) - a collection with this new fragment will show some kind of ‘helpful warning’ about missing return value info only visible for core 2.20 and above.
…and we did do a bit of ‘squinting/ignoring’ on the backport of that warning - considering it a bugfix is a bit of a ..squint/ignore, and the more ‘purist’ approach is D - it only exists in 2.20, and we’d probably have to remember in 18 months to socialize this new fragment at the point when most collection maintainers would actually consider implementing it.
Red Hat User - AAP products that consume ansible-core are multiple releases behind (aka core 2.15, 2.16). Even if we backport, I’m not sure we’d backport that far back? If so, sounds like option E) would leave many Red Hat customers with funky error messages. Some customers will likely be using community collections that implement this new fragment type. We probably can’t optimize for this scenario as community collection use by customers is probably ‘use at own risk’ so to speak (random guess on my part). So best we could do is make the error as clear as possible.
Certified Collection maintainer - We know some collection maintainers have their collections available in community as well as ‘certified’ in Red Hat land. These folks are again more likely to add the new fragment type, because they are more involved in community, and then have customers complaining about wonky error messsages when they use the collection with the Red Hat product. - We could probably ensure these certified collection maintainers are made aware of the implications of implementing this new fragment any time in the next …erm.. 3 years or whatever.
Red Hat AAP product - Similar to the first item, the product is mutliple core releases behind. A collection that includes this new fragment will likely show up as ??? broken?? in the Hub display? Unlike docs.ansible.com, Hub wouldn’t have the new fragment recognized for ‘some time to come’ so not sure what would show up there? This is similar to the certified collection problem - Perhaps we tell these collection owners they should not implement the feature until the red hat product supports core 2.20 and above.
dev-tools (aka ansible-navigator) - Taking another random guess - navigator also displays the docs using ansible-doc. If navigator is from an older core version - what happens to what it attempts to display if it’s looking at a collection that includes this new fragment? I’m unsure what navigator does when ansible-doc returns an error.
galaxy - Similar to the AAP product, Galaxy wouldn’t have support for this new fragment right away. So what happens in Galaxy display when you get an unsupported fragment like this?
do you mean D)? … E) is to remove the feature, this seems to be a mix of things.
to display a ‘helpful warning’ we need to backport a feature that detects this, this is not something I can get accepted by the stable branch maintainers and would also be very limited, 2.18 at most, which is mostly what A) is.
).