From b08d98ba8ec1ed52e72eae9b69c92943fc143b8c Mon Sep 17 00:00:00 2001 From: Matthew Davis Date: Fri, 18 Nov 2022 21:31:28 +1100 Subject: [PATCH 1/5] docs: Add more information about running integration tests --- CONTRIBUTING.md | 102 ++++++++++++++---- README.md | 9 +- .../fragments/924-contributing-docs.yml | 3 + 3 files changed, 83 insertions(+), 31 deletions(-) create mode 100644 changelogs/fragments/924-contributing-docs.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a61b0a1120..acd6197f9ae 100644 --- a/CONTRIBUTING.md +++ b/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,57 @@ 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). +You need to explicitly create credentials and load them in. +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. 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 +90,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 CI bot 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/dev_guide/platforms/aws_guidelines.html) +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 diff --git a/README.md b/README.md index d88137fb098..f035072a442 100644 --- a/README.md +++ b/README.md @@ -95,19 +95,12 @@ You can either call modules by their Fully Qualified Collection Name (FQCN), suc ## Contributing to this collection We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [Amazon AWS collection repository](https://github.com/ansible-collections/amazon.aws). -See [Contributing to Ansible-maintained collections](https://docs.ansible.com/ansible/devel/community/contributing_maintained_collections.html#contributing-maintained-collections) for more details. +See [CONTRIBUTING.md](CONTRIBUTING.md) for more details. You can also join us on: - Libera.Chat IRC - the ``#ansible-aws`` [irc.libera.chat](https://libera.chat/) channel -### More information about contributing - -- [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 -- [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) - ## Release notes See the [rendered changelog](https://ansible-collections.github.io/amazon.aws/branch/main/collections/amazon/aws/docsite/CHANGELOG.html) or the [raw generated changelog](https://github.com/ansible-collections/amazon.aws/tree/main/CHANGELOG.rst). diff --git a/changelogs/fragments/924-contributing-docs.yml b/changelogs/fragments/924-contributing-docs.yml new file mode 100644 index 00000000000..3f8b401ffe3 --- /dev/null +++ b/changelogs/fragments/924-contributing-docs.yml @@ -0,0 +1,3 @@ +minor_changes: + - CONTRIBUTING.md - refactors and adds to contributor documentation (https://github.com/ansible-collections/amazon.aws/issues/924) + From ec04ea6928d05976940b8dbbb716212480dfa44c Mon Sep 17 00:00:00 2001 From: Matthew Davis Date: Mon, 28 Nov 2022 14:15:08 +1100 Subject: [PATCH 2/5] update CONTRIBUTING.md links --- CONTRIBUTING.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index acd6197f9ae..3984c29c40b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,8 +51,10 @@ 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). -You need to explicitly create credentials and load them in. +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. @@ -66,6 +68,7 @@ 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. @@ -104,7 +107,7 @@ 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) +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 From 2649f6fbdb0c6cf0447cebca5d4d21c8d17a39cf Mon Sep 17 00:00:00 2001 From: Matthew Davis Date: Tue, 29 Nov 2022 12:49:18 +1100 Subject: [PATCH 3/5] make link from README to CONTRIBUTING less fragile --- README.md | 2 +- docs/docsite/extra-docs.yml | 3 +++ docs/docsite/rst/CONTRIBUTING.md | 1 + 3 files changed, 5 insertions(+), 1 deletion(-) create mode 120000 docs/docsite/rst/CONTRIBUTING.md diff --git a/README.md b/README.md index f035072a442..aa45dd6266e 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ You can either call modules by their Fully Qualified Collection Name (FQCN), suc ## Contributing to this collection We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [Amazon AWS collection repository](https://github.com/ansible-collections/amazon.aws). -See [CONTRIBUTING.md](CONTRIBUTING.md) for more details. +See [CONTRIBUTING.md](https://ansible-collections.github.io/amazon.aws/branch/main/collections/amazon/aws/docsite/CONTRIBUTING.html) for more details. You can also join us on: diff --git a/docs/docsite/extra-docs.yml b/docs/docsite/extra-docs.yml index aeb1528477b..d0534103417 100644 --- a/docs/docsite/extra-docs.yml +++ b/docs/docsite/extra-docs.yml @@ -6,6 +6,9 @@ sections: - title: Scenario Guide toctree: - guide_aws + - title: Contributing + toctree: + - CONTRIBUTING - title: Module Development Guidelines toctree: - dev_guidelines diff --git a/docs/docsite/rst/CONTRIBUTING.md b/docs/docsite/rst/CONTRIBUTING.md new file mode 120000 index 00000000000..c97564d93a7 --- /dev/null +++ b/docs/docsite/rst/CONTRIBUTING.md @@ -0,0 +1 @@ +../../../CONTRIBUTING.md \ No newline at end of file From 7b69c2ff04629134c8672edfbf10a7fcef0ae80a Mon Sep 17 00:00:00 2001 From: Mark Chappell Date: Tue, 29 Nov 2022 12:26:47 +0100 Subject: [PATCH 4/5] Apply suggestions from code review --- README.md | 2 +- docs/docsite/extra-docs.yml | 3 --- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/README.md b/README.md index aa45dd6266e..5f91270d6c6 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ You can either call modules by their Fully Qualified Collection Name (FQCN), suc ## Contributing to this collection We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [Amazon AWS collection repository](https://github.com/ansible-collections/amazon.aws). -See [CONTRIBUTING.md](https://ansible-collections.github.io/amazon.aws/branch/main/collections/amazon/aws/docsite/CONTRIBUTING.html) for more details. +See [CONTRIBUTING.md](https://github.com/ansible-collections/amazon.aws/blob/main/CONTRIBUTING.md) for more details. You can also join us on: diff --git a/docs/docsite/extra-docs.yml b/docs/docsite/extra-docs.yml index d0534103417..aeb1528477b 100644 --- a/docs/docsite/extra-docs.yml +++ b/docs/docsite/extra-docs.yml @@ -6,9 +6,6 @@ sections: - title: Scenario Guide toctree: - guide_aws - - title: Contributing - toctree: - - CONTRIBUTING - title: Module Development Guidelines toctree: - dev_guidelines From 8b08c34b8b354ce9de6cb7a53f3cc34a4e33ea89 Mon Sep 17 00:00:00 2001 From: Mark Chappell Date: Tue, 29 Nov 2022 12:26:58 +0100 Subject: [PATCH 5/5] Delete CONTRIBUTING.md --- docs/docsite/rst/CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) delete mode 120000 docs/docsite/rst/CONTRIBUTING.md diff --git a/docs/docsite/rst/CONTRIBUTING.md b/docs/docsite/rst/CONTRIBUTING.md deleted file mode 120000 index c97564d93a7..00000000000 --- a/docs/docsite/rst/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -../../../CONTRIBUTING.md \ No newline at end of file