From 024e7419da8ec50a94799d5fa22004c2298b7935 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 26 Jul 2021 16:54:00 +0200 Subject: [PATCH] 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 | 24 ++++++++++++++---------- CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++ tests/sanity/extra/botmeta.py | 24 ++++++++++-------------- 3 files changed, 55 insertions(+), 24 deletions(-) diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index b91d01d44e..fb08599a13 100644 --- a/.github/BOTMETA.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4dfde91fca..ba30ed1e02 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/tests/sanity/extra/botmeta.py b/tests/sanity/extra/botmeta.py index 43bd087aa5..b5c49b5a4b 100755 --- a/tests/sanity/extra/botmeta.py +++ b/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 REPORT_MISSING_MAINTAINERS: - print('%s:%d:%d: %s' % (FILENAME, 0, 0, 'No (active or inactive) maintainer mentioned for %s' % filename)) - return - if filename.startswith('plugins/filter/'): - return - maintainers = read_authors(filename) - 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: + if not filename.startswith('plugins/filter/'): + maintainers = read_authors(filename) + 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)) 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():