BOTMETA: enforce entries for new plugins/modules, add documentation for creating new plugins/modules (#3088)

* More BOTMETA improvements.

* Improve BOTMETA test, start reporting missing entries for new plugins/modules.

* Add instructions for creating new plugins and modules.

.github/BOTMETA.yml

@@ -123,10 +123,12 @@ files:
     maintainers: Ajpantuso
   $filters/jc.py:
     maintainers: kellyjonbrazil
+  $filters/json_query.py: {}
   $filters/list.py:
     maintainers: vbotka
   $filters/path_join_shim.py:
     maintainers: felixfontein
+  $filters/random_mac.py: {}
   $filters/time.py:
     maintainers: resmo
   $filters/version_sort.py:
@@ -204,7 +206,7 @@ files:
   $lookups/random_string.py:
     maintainers: Akasurde
   $lookups/redis.py:
-    maintainers: jpmens
+    maintainers: $team_ansible_core jpmens
   $lookups/shelvefile.py: {}
   $lookups/tss.py:
     maintainers: amigus
@@ -591,8 +593,6 @@ files:
     maintainers: gthiemonge
   $modules/net_tools/haproxy.py:
     maintainers: ravibhure Normo
-  $modules/net_tools/:
-    maintainers: nerzhul
   $modules/net_tools/infinity/infinity.py:
     maintainers: MeganLiu
   $modules/net_tools/ip_netns.py:
@@ -616,8 +616,10 @@ files:
     ignore: andyhky
   $modules/net_tools/netcup_dns.py:
     maintainers: nbuchwitz
+  $modules/net_tools/nsupdate.py:
+    maintainers: nerzhul
   $modules/net_tools/omapi_host.py:
-    maintainers: amasolov
+    maintainers: amasolov nerzhul
   $modules/net_tools/pritunl/:
     maintainers: Lowess
   $modules/net_tools/nios/:
@@ -692,7 +694,7 @@ files:
     labels: rocketchat
     ignore: ramondelafuente
   $modules/notification/say.py:
-    maintainers: ansible mpdehaan
+    maintainers: $team_ansible_core mpdehaan
   $modules/notification/sendgrid.py:
     maintainers: makaimc
   $modules/notification/slack.py:
@@ -717,7 +719,7 @@ files:
   $modules/packaging/language/easy_install.py:
     maintainers: mattupstate
   $modules/packaging/language/gem.py:
-    maintainers: ansible johanwiren
+    maintainers: $team_ansible_core johanwiren
     labels: gem
   $modules/packaging/language/maven_artifact.py:
     maintainers: tumbl3w33d turb
@@ -978,7 +980,7 @@ files:
   $modules/system/dpkg_divert.py:
     maintainers: quidame
   $modules/system/facter.py:
-    maintainers: ansible gamethis
+    maintainers: $team_ansible_core gamethis
     labels: facter
   $modules/system/filesystem.py:
     maintainers: pilou- abulimov quidame
@@ -1023,7 +1025,7 @@ files:
   $modules/system/nosh.py:
     maintainers: tacatac
   $modules/system/ohai.py:
-    maintainers: ansible mpdehaan
+    maintainers: $team_ansible_core mpdehaan
     labels: ohai
   $modules/system/open_iscsi.py:
     maintainers: srvg
@@ -1104,7 +1106,7 @@ files:
   $modules/web_infrastructure/gunicorn.py:
     maintainers: agmezr
   $modules/web_infrastructure/htpasswd.py:
-    maintainers: ansible
+    maintainers: $team_ansible_core
     labels: htpasswd
   $modules/web_infrastructure/jboss.py:
     maintainers: $team_jboss jhoekx
@@ -1124,7 +1126,9 @@ files:
     labels: jira
   $modules/web_infrastructure/nginx_status_info.py:
     maintainers: resmo
-  $modules/web_infrastructure/:
+  $modules/web_infrastructure/rundeck_acl_policy.py:
+    maintainers: nerzhul
+  $modules/web_infrastructure/rundeck_project.py:
     maintainers: nerzhul
   $modules/web_infrastructure/sophos_utm/:
     maintainers: $team_e_spirit

CONTRIBUTING.md

@@ -34,3 +34,34 @@ You can also read [our Quick-start development guide](https://github.com/ansible
 If you want to test a PR locally, refer to [our testing guide](https://github.com/ansible/community-docs/blob/main/test_pr_locally_guide.rst) for instructions on how do it quickly.
 
 If you find any inconsistencies or places in this document which can be improved, feel free to raise an issue or pull request to fix it.
+
+## Creating new modules or plugins
+
+Creating new modules and plugins requires a bit more work than other Pull Requests.
+
+1. Please make sure that your new module or plugin is of interest to a larger audience. Very specialized modules or plugins that
+   can only be used by very few people should better be added to more specialized collections.
+
+2. When creating a new module or plugin, please make sure that you follow various guidelines:
+
+   - Follow [development conventions](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html);
+   - Follow [documentation standards](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html) and
+     the [Ansible style guide](https://docs.ansible.com/ansible/devel/dev_guide/style_guide/index.html#style-guide);
+   - Make sure your modules and plugins are [GPL-3.0-or-later](https://www.gnu.org/licenses/gpl-3.0-standalone.html) licensed
+     (new module_utils can also be [BSD-2-clause](https://opensource.org/licenses/BSD-2-Clause) licensed);
+   - Make sure that new plugins and modules have tests (unit tests, integration tests, or both); it is preferable to have some tests
+     which run in CI.
+
+3. For modules and action plugins, make sure to create your module/plugin in the correct subdirectory, and create a symbolic link
+   from `plugins/modules/` respectively `plugins/action/` to the actual module/plugin code. (Other plugin types should not use
+   subdirectories.)
+
+   - Action plugins need to be accompanied by a module, even if the module file only contains documentation
+     (`DOCUMENTATION`, `EXAMPLES` and `RETURN`). The module must have the same name and directory path in `plugins/modules/`
+     than the action plugin has in `plugins/action/`.
+
+4. Make sure to add a BOTMETA entry for your new module/plugin in `.github/BOTMETA.yml`. Search for other plugins/modules in the
+   same directory to see how entries could look. You should list all authors either as `maintainers` or under `ignore`. People
+   listed as `maintainers` will be pinged for new issues and PRs that modify the module/plugin or its tests.
+
+   When you add a new plugin/module, we expect that you perform maintainer duty for at least some time after contributing it.

tests/sanity/extra/botmeta.py

@@ -17,7 +17,7 @@ from voluptuous import Required, Schema, Invalid
 from voluptuous.humanize import humanize_error
 
 
-REPORT_MISSING_MAINTAINERS = False
+REPORT_NO_MAINTAINERS = False
 
 FILENAME = '.github/BOTMETA.yml'
 
@@ -73,20 +73,16 @@ def validate(filename, filedata):
         return
     # Compile lis tof all active and inactive maintainers
     all_maintainers = filedata['maintainers'] + filedata['ignore']
-    if not all_maintainers:
+    if not filename.startswith('plugins/filter/'):
-        if REPORT_MISSING_MAINTAINERS:
+        maintainers = read_authors(filename)
-            print('%s:%d:%d: %s' % (FILENAME, 0, 0, 'No (active or inactive) maintainer mentioned for %s' % filename))
+        for maintainer in maintainers:
-        return
+            maintainer = extract_author_name(maintainer)
-    if filename.startswith('plugins/filter/'):
+            if maintainer is not None and maintainer not in all_maintainers:
-        return
+                msg = 'Author %s not mentioned as active or inactive maintainer for %s (mentioned are: %s)' % (
-    maintainers = read_authors(filename)
+                    maintainer, filename, ', '.join(all_maintainers))
-    for maintainer in maintainers:
-        maintainer = extract_author_name(maintainer)
-        if maintainer is not None and maintainer not in all_maintainers:
-            msg = 'Author %s not mentioned as active or inactive maintainer for %s (mentioned are: %s)' % (
-                maintainer, filename, ', '.join(all_maintainers))
-            if REPORT_MISSING_MAINTAINERS:
                 print('%s:%d:%d: %s' % (FILENAME, 0, 0, msg))
+    if not all_maintainers and REPORT_NO_MAINTAINERS:
+        print('%s:%d:%d: %s' % (FILENAME, 0, 0, 'No (active or inactive) maintainer mentioned for %s' % filename))
 
 
 def main():