Update module default groups documentation

[mariolenz]

Fixes #1759

It looks like default groups / action groups are stable. I think we should update the documentation accordingly, since it still says it's a preview feature.

I've also learned that that there is some magic happening for some special groups for reasons of downwards compatibility or whatever:

https://github.com/ansible/ansible/blob/b5ae8a382baca04442ad82e654ab6e35379844c3/lib/ansible/config/ansible_builtin_runtime.yml#L9685

I think we should document this also.

[mariolenz]

Thanks for reviewing @felixfontein!

[mariolenz]

@s-hertel Since you've answered my original question (#1759) I thought you might be interested in having a look at this PR.

[felixfontein]

One general thing I'm wondering about this documentation is: why is part of the syntax for collection development documented here? There's also a separate set of documentation for this feature in dev_guide/developing_collections_structure.rst, which also mentions the special metadata: entry:

- *action_groups*

  A mapping of groups and the list of action plugin and module names they contain. They may also have a special 'metadata' dictionary in the list, which can be used to include actions from other groups.

  .. code:: yaml

     action_groups:
       groupname:
         # The special metadata dictionary. All action/module names should be strings.
         - metadata:
             extend_group:
               - another.collection.groupname
               - another_group
         - my_action
       another_group:
         - my_module
         - another.collection.another_module

Maybe the meta/runtime part of the documentation here should be deleted, and the other documentation should be referenced instead?

(There's also essentially no validation of action_groups in the ansible-core sanity tests. They only make sure that action_groups is a dictionary if it's specified, but nothing else...)

[s-hertel]

One general thing I'm wondering about this documentation is: why is part of the syntax for collection development documented here?

I added both in 74039. Linking to the other would be better, I think I just wanted to make sure it was mentioned both places.

Adding a good sanity test seems like it should be a prerequisite for documenting this as no longer preview. Fwiw, I made the runtime behavior for action_groups very forgiving, it's at most a warning, and there's a toggle to ignore invalid action_groups: https://github.com/ansible/ansible/blob/devel/lib/ansible/playbook/base.py#L33-L69.

[mariolenz]

Yes, this is a little bit weird. I should say that this file should document how to use module defaults, but not how to implement them in a collection.

[felixfontein]

Can you add the following (or something similar) after the code block below (I cannot add a comment there directly):

More information on meta/runtime.yml, including the complete format for `action_groups`, can be found in :ref:`meta_runtime_yml`.

[mariolenz]

Can you add the following (or something similar) after the code block below (I cannot add a comment there directly):

More information on meta/runtime.yml, including the complete format for `action_groups`, can be found in :ref:`meta_runtime_yml`.

@felixfontein Like this?

[felixfontein]

Yes, this is a little bit weird. I should say that this file should document how to use module defaults, but not how to implement them in a collection.

I agree, though right now users often have to consult the implementation to find out which module default groups are available and which actions they cover. (You can document this with attributes for an individual module/action, but not every collection is doing that. And even that doesn't give you a list of all actions in an action group either, it only tells you for a specific action whether its in there. So being able to look at meta/runtime.yml right now is a necessary skill for users of action groups...)

[felixfontein]

I created a better validation test in ansible/ansible#83965.