Adding upstream version 9.4.0+dfsg.upstream/9.4.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 87 insertions, 30 deletions

diff --git a/ansible_collections/community/aws/CONTRIBUTING.md b/ansible_collections/community/aws/CONTRIBUTING.md
index db74cf119..eb41c9274 100644
--- a/ansible_collections/community/aws/CONTRIBUTING.md
+++ b/ansible_collections/community/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 boto 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.
 
 ### community.aws
 This collection contains modules and plugins contributed and maintained by the Ansible AWS
@@ -30,19 +20,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 `community.aws` collection is no exception. When you find a bug, 
+All software has bugs, and the `community.aws` collection is no exception. When you find a bug,
 you can help tremendously by [telling us about it](https://github.com/ansible-collections/community.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
-
-All modules MUST have integration tests for new features. Upgrading to boto3 shall be considered a feature request.  
-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.
+## 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.
+
+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
@@ -60,22 +91,48 @@ 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 be found on [libera.chat](https://libera.chat/) IRC as detailed below.
+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/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.
 
-### Changelog Fragment
 
-Once a PR has been created, make sure to create a changelog [fragment](https://github.com/ansible-collections/community.aws/tree/main/changelogs/fragments).
+- [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)
 
-For more information on changelog fragments then refer to the guide found [here](https://docs.ansible.com/ansible/latest/community/development_process.html#changelogs).
 
 ### Code of Conduct
-The `community.aws` collection follows the Ansible project's 
-[Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html). 
+The `community.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 [Libera.Chat's Nickname Registration guide](https://libera.chat/guides/registration) for instructions.
+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 of the `community.aws` collection.
+The `#ansible-aws` channel on [irc.libera.chat](https://libera.chat/) is the main and official place to discuss use and development
+of the `community.aws` collection.