Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document steps to create a module (developer guide) #923

Open
1 task done
sebastien-rosset opened this issue Jan 15, 2022 · 2 comments
Open
1 task done

Document steps to create a module (developer guide) #923

sebastien-rosset opened this issue Jan 15, 2022 · 2 comments
Labels

Comments

@sebastien-rosset
Copy link
Contributor

sebastien-rosset commented Jan 15, 2022

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. ansible-collections/community.aws@70e2de7
    2. ansible-collections/community.aws@ef29b3a
    3. ansible-collections/community.aws@c166616
  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: ec2_vol: Add check_mode support to ec2_vol #509 (comment)
  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

  • I agree to follow the Ansible Code of Conduct
@tremble tremble transferred this issue from ansible-collections/community.aws Jul 10, 2022
@tremble
Copy link
Contributor

tremble commented Jul 10, 2022

@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
Copy link
Contributor

samccann commented Oct 7, 2022

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)...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

5 participants