Document steps to create a module (developer guide)

[sebastien-rosset]

Summary

While creating the opensearch module, I missed a few step that are not documented in CONTRIBUTING.md. It would help a lot to document these steps.

Issue Type

Documentation Report

Component Name

opensearch

Ansible Version

$ ansible --version

Collection Versions

$ ansible-galaxy collection list

Configuration

$ ansible-config dump --only-changed

OS / Environment

No response

Additional Information

When a developer submits a PR for a new module:

1. Where to do git clone. The path and directory names are important. It should be cloned under ~/collections/ansible_collections/community/aws otherwise the local tests will fail.
2. How to handle a situation when the new module needs a version of boto3 and botocore which is higher than the default. Examples:
   1. https://github.com/ansible-collections/community.aws/pull/859/commits/70e2de7cd0fc45bafe4d4dd92d767bfbf936bbbc
   2. https://github.com/ansible-collections/community.aws/pull/859/commits/ef29b3aff3d683d5a1deb379eab12e83eaffc1b8
   3. https://github.com/ansible-collections/community.aws/pull/859/commits/c1666165df91f43e16d17fb19a90e7165b67a832
3. How to add the module to group/aws such that the module defaults work in the integration tests main.yml file. Add to meta/runtime.yml? If the module is not added to the group, the module is not getting the module defaults. In that case, the boto3 API fails and the error message states the region is not set (because the region was set in the main.yml file but the module is not getting the value).
4. What files to modify? Some of them are obvious, like creating the module and the integration tests, but changes like runtime.yml are less obvious. Maybe there are other files like list of modules, documentation, change log?
5. Explain difference between tiny_prefix and resource_prefix in the integration tests.
6. Steps by step instructions to run the sanity tests and integration tests locally.
7. Explain recommendations for integration tests, specifically this one: https://github.com/ansible-collections/amazon.aws/pull/509#issuecomment-932056400
8. Guideline for setting the value version_added: X.Y.Z in the new module.
9. Indicate the module should support check_mode.

The tests/requirements.yml file specifies dependencies such as community.crypto. These dependencies need to be manually installed before running the tests:

# git clone [email protected]:ansible-collections/community.aws.git ~/collections/ansible_collections/community/aws
# ansible-galaxy collection install amazon.aws -p ~/collections
# ansible-galaxy collection install community.crypto -p ~/collections
# ansible-galaxy collection install ansible.netcommon -p ~/collections

It would be worth indicating the tests/requirements.yml file does not have the format expected by ansible-galaxy.

Code of Conduct

• [X] I agree to follow the Ansible Code of Conduct

[tremble]

@sebastien-rosset I think this would be a really good addition to our documentation, however the docs for amazon.aws and community.aws live over in amazon.aws. so I've transferred this issue over to amazon.aws

[samccann]

Hi folks - we have some generic 'contributing to collections' documentation at https://docs.ansible.com/ansible/latest/community/create_pr_quick_start.html

And some about testing at: https://docs.ansible.com/ansible/latest/community/collection_contributors/test_index.html

If we link to these from the CONTRIBUTOR file, does this cover a lot of what's been pointed out here as problematic? (things that aren't specific to AWS collection development)...