8.3 KiB
Contributing
Please Help to Improve this Project
You would like to contribute to this project and want to know how to do that? Let me tell you first that you are awesome because you take care! Let's make this Ansible collection even better. Any contributions and help to improve this project via issues, pull requests and more are most welcome and much appreciated. We are here to help you with your contributions at any time. Please mention us in issues and pull requests if you need help or if you have questions.
Why Do We Need Contributors and Contributions
Coding is team-work and open-source software is community-work. In order to enhance the project or correct bugs and regressions in the project we need you and your support because the project benefits from your expertise, knowledge, opinions, perspectives, and labour. Together we are improving this Ansible collection step-by-step. Please follow these guidelines and be respectful as we respect your work and your contributions in the same manner and support you and help you with your contributions. Feel free to get into contact with us or with other contributors as the community will help you with your questions and contributions.
Contributions We are Looking For
There are different ways to contribute to this project:
- Discuss issues and pull requests
- Submit bug reports or contribute new feature proposals
- Contribute fixes or implement new features
- Do testing
Investigate Before Contributing
Before you start contributing and create issues and pull requests we ask you to first check whether an issue or pull request already exists for the error, enhancement, feature or test case you have in mind.
Discuss Issues and Pull Requests
You can contribute by participating in discussions you find in issues and pull requests or by starting your own discussions.
Submit Bug Reports or Contribute New Feature Proposals
If you found a bug in the Ansible collection or a typo in the documentation or if you would like to discuss or suggest functional or quality aspects of the collection you are welcome to create issues to get in contact with us.
Contribute Fixes or Implement New Features
If you would like to provide a fix for a bug or a typo in the documentation or even add or change specific features of the collection or specific parts of the documentation, you are welcome to fork this repository, create a separate branch, create a pull request and add your contributions. Please also label the pull request, refer to related issues and assign reviewers that take care of reviewing your suggested changes. We would like you to check that the CI pipeline passes before asking reviewers to review your suggestions.
Do Testing
While automated tests are by far our preferred testing method we also acknowledge contributors doing exploratory testing. Sometimes the existing automated tests are not sufficient to account for specific corner cases and to reveal hidden bugs. Testing the collection manually is always a good approach to make sure that the collection passes a particular additional test case. Even more valuable are automated tests because they are repeatable. That is why these test methods work best in combination. Once a bug is revealed in an exploratory test, additional automated test-cases need to be added that mark this behaviour as a defect. As a consequence, a fix need to be developed that makes the CI pipeline and the new regression tests pass again. Please feel free to support the project by providing automated test cases. In order to do so you need to fork the repository, create a separate branch, create a pull request and add the test cases and fixes to that new branch. Please also use labels for your pull request, name issues that you refer to and assign reviewers who would be able to review your suggested test cases and fixes. Please make sure that the CI pipeline passes before you name reviewers for your pull request.
GitHub Actions CI Pipeline and Code Reviews
Finally, as soon as your changes are ready and you would like to ask someone to review your contributions you need to check that all GitHub Actions CI pipeline jobs pass in your pull request before assigning reviewers to your pull request.
Contributions Workflow via Pull Requests
In summary, if you would like to contribute with pull requests for enhancements, bug-fixes or test cases, we kindly ask you to follow this workflow:
For those of you who want to know how forked-based contributions work on GitHub, we would like to point to the GitHub Docs about contributing to projects.
Set Up a Local Development Environment (Optional)
In order to add contributions via pull requests you most probably need to create a local development environment to make sure that your changes work as expected. After cloning the project locally the Python dependencies need to be installed:
$ pipenv install --dev
As mentioned in the suggested contribution workflow above, linting and testing your contributions locally is optional, but we encourage you to do so. The following sections show how to lint and test your contributions locally.
Linting the Project
This collection is linted via Ansible Lint and yamllint which guarantees that the collection adheres to a set of Ansible Lint rules and yamllint rules:
$ pipenv run ansible-lint --offline
REUSE Specification Compliance
Each file in this project needs to have a proper license and copyright header. Please check that each file you add to the project contains license and copyright information and that it thereby meets the REUSE Specification:
$ pipenv run reuse lint
Testing the Ansible Collection
This collection is tested via Ansible Molecule. During development of your changes we would like you to use Molecule and the existing automated test cases to verify that your changes do not break existing test cases:
$ pipenv run molecule test -s unattended_upgrades
How are Contributors Given Credit for Their Valuable Work?
Please add yourself to the list of contributors in file README.md via a pull request if you made significant contributions to this collection. Significant contributions are done by suggesting pull requests that fix bugs or add features or test cases to the project. Since all other contributions are welcome and may be significant as well you can request to be added as a contributor which is then decided on a case-by-case basis.
Ground Rules and Contributions We are Not Looking For
While we welcome and appreciate all contributions we want people to be kind, respectful and mindful and won't support people who aren't. Please help and support each other. In order to get an idea what this actually means and involves we would like to ask you to read the Codes of Conduct of The Carpentries, the Ansible Community, and the GitLab Community.