diff options
Diffstat (limited to 'ansible_collections/amazon/aws/CONTRIBUTING.md')
| -rw-r--r-- | ansible_collections/amazon/aws/CONTRIBUTING.md | 105 |
1 files changed, 82 insertions, 23 deletions
diff --git a/ansible_collections/amazon/aws/CONTRIBUTING.md b/ansible_collections/amazon/aws/CONTRIBUTING.md index 2a61b0a11..17be9b7d7 100644 --- a/ansible_collections/amazon/aws/CONTRIBUTING.md +++ b/ansible_collections/amazon/aws/CONTRIBUTING.md @@ -1,15 +1,5 @@ # Contributing -## Getting Started - -General information about setting up your Python environment, testing modules, -Ansible coding styles, and more can be found in the [Ansible Community Guide]( -https://docs.ansible.com/ansible/latest/community/index.html). - -Information about AWS SDK library usage, module utils, testing, and more can be -found in the [AWS Guidelines](https://docs.ansible.com/ansible/devel/dev_guide/platforms/aws_guidelines.html) -documentation. - ## AWS Collections There are two related collections containing AWS content (modules and plugins). @@ -18,7 +8,7 @@ There are two related collections containing AWS content (modules and plugins). This collection contains the `module_utils` (shared libraries) used by both collections. Content in this collection is included downstream in Red Hat Ansible Automation Platform. -Code standards, test coverage, and other supportability criteria may be higher in this collection. +Code standards, test coverage, and other supportability criteria may be higher in this collection. The `amazon.aws` collection is an [Ansible-maintained collection](https://docs.ansible.com/ansible/devel/community/contributing_maintained_collections.html). @@ -32,19 +22,60 @@ Content in this collection that is stable and meets other acceptance criteria ha to be promoted and migrated into `amazon.aws`. ## Submitting Issues -All software has bugs, and the `amazon.aws` collection is no exception. When you find a bug, +All software has bugs, and the `amazon.aws` collection is no exception. When you find a bug, you can help tremendously by [telling us about it](https://github.com/ansible-collections/amazon.aws/issues/new/choose). -If you should discover that the bug you're trying to file already exists in an issue, -you can help by verifying the behavior of the reported bug with a comment in that +If you should discover that the bug you're trying to file already exists in an issue, +you can help by verifying the behavior of the reported bug with a comment in that issue, or by reporting any additional information -## Pull Requests +## Writing New Code + +New modules should be submitted to the [community.aws](https://github.com/ansible-collections/community.aws) collection. + +For new features and bug fixes on existing modules, +clone this repository and try to run unit tests and integration tests by following +[these instructions](https://docs.ansible.com/ansible/latest/community/create_pr_quick_start.html). +When you get to this part: + +``` +ansible-test integration name_of_test_subdirectory --docker -v +``` + +Run this from the `tests` directory of this repository. +Substitute `name_of_test_subdirectory` for the name of the relevant directory within `tests/integration/targets`. +You'll get this error: + +``` +WARNING: Excluding tests marked "cloud/aws" which require config +(see "/home/dev/ansible/ansible/test/lib/ansible_test/config/cloud-config-aws.ini.template"): ec2_group +``` +This is because the unit tests don't automatically detect the AWS credentials on your machine +unlike plain `boto3` and the `aws` cli. +(Typically because they're run inside Docker, which can't access `~/.aws/credentials`. +But even when running tests outside docker, the tests ignore `~/.aws/credentials`.) +You need to explicitly create credentials and load them in to an Ansible-specific file. +To do this, copy the file mentioned in that error message, +into the clone of this repo, under `tests/integration/cloud-config-aws.ini`. +Modify the `@` variables, pasting in an IAM secret credential. +If you don't need the `secret_token` (most IAM users don't), comment that line out. + +You can use an AWS account that already has unrelated resources in it. +The tests should not touch pre-existing resources, and should tidy up after themselves. +(Of course for security reasons you may want to run in a dedicated AWS account.) + +If you're only writing a pull request for one AWS service +you are able to create credentials only with permissions required for that test. +For example, to test the Lambda modules, you only need Lambda permissions, +and permissions to create IAM roles. +You could also deploy [the policies used by the CI](https://github.com/mattclay/aws-terminator/tree/master/aws/policy). All modules MUST have integration tests for new features. Bug fixes for modules that currently have integration tests SHOULD have tests added. -New modules should be submitted to the [community.aws](https://github.com/ansible-collections/community.aws) collection -and MUST have integration tests. + +Once you're able to run integration tests for the existing code, +now start by adding tests in `tests/integration/targets` +for your new feature or tests for the bug(s) you're about to fix. Expected test criteria: * Resource creation under check mode @@ -62,19 +93,47 @@ Expected test criteria: Where modules have multiple parameters we recommend running through the 4-step modification cycle for each parameter the module accepts, as well as a modification cycle where as most, if not all, parameters are modified at the same time. -For general information on running the integration tests see the -[Integration Tests page of the Module Development Guide](https://docs.ansible.com/ansible/devel/dev_guide/testing_integration.html#testing-integration), -especially the section on configuration for cloud tests. For questions about writing tests the Ansible AWS community can +After writing the tests, now write/modify the module code, typically in `plugins/modules`. +Don't forget to add [a changelog entry](https://docs.ansible.com/ansible/latest/community/collection_development_process.html#collection-changelog-fragments). +Then create a pull request. + +If you're struggling with running integration tests locally, don't worry. +After creating a pull request the GitHub Actions will automatically test for you. + +## More information about contributing + +General information about setting up your Python environment, testing modules, +Ansible coding styles, and more can be found in the [Ansible Community Guide]( +https://docs.ansible.com/ansible/latest/community/index.html). + +Information about AWS SDK library usage, module utils, testing, and more can be +found in the [AWS Guidelines](https://docs.ansible.com/ansible/devel/collections/amazon/aws/docsite/dev_guidelines.html#ansible-collections-amazon-aws-docsite-dev-guide-intro) +documentation. + +For general information on running the integration tests see +[this page](https://docs.ansible.com/ansible/latest/community/collection_contributors/test_index.html) and +[Integration Tests page of the Module Development Guide](https://docs.ansible.com/ansible/devel/dev_guide/testing_integration.html#non-destructive-tests). +Ignore the part about `source hacking/env-setup`. That's only applicable for working on `ansible-core`. +You should be able to use the `ansible-test` that's installed with Ansible generally. +Look at [the section on configuration for cloud tests](https://docs.ansible.com/ansible/devel/dev_guide/testing_integration.html#other-configuration-for-cloud-tests). +For questions about writing tests the Ansible AWS community can be found on Libera.Chat IRC as detailed below. +- [Ansible Community Guide](https://docs.ansible.com/ansible/latest/community/index.html) - Details on contributing to Ansible +- [Contributing to Collections](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#contributing-to-collections) - How to check out collection git repositories correctly +- [Contributing to Ansible-maintained collections](https://docs.ansible.com/ansible/devel/community/contributing_maintained_collections.html#contributing-maintained-collections) +- [Guidelines for Ansible Amazon AWS module development](https://docs.ansible.com/ansible/latest/dev_guide/platforms/aws_guidelines.html) +- [Getting Started With AWS Ansible Module Development and Community Contribution](https://www.ansible.com/blog/getting-started-with-aws-ansible-module-development) + + ### Code of Conduct -The `amazon.aws` collection follows the Ansible project's -[Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html). +The `amazon.aws` collection follows the Ansible project's +[Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html). Please read and familiarize yourself with this document. ### IRC -Our IRC channels may require you to register your nickname. If you receive an error when you connect, see +Our IRC channels may require you to register your nickname. If you receive an error when you connect, see [Libera.Chat's Nickname Registration guide](https://libera.chat/guides/registration) for instructions. The `#ansible-aws` channel on [irc.libera.chat](https://libera.chat/) is the main and official place to discuss use and development |