|
| 1 | +# Contribution Guidelines |
| 2 | + |
| 3 | +First and foremost, we’d like to express our gratitude to you for taking the time to contribute. |
| 4 | +We welcome and appreciate any and all contributions via |
| 5 | +[Pull Requests] along the [GitHub Flow]. |
| 6 | + |
| 7 | +- [Contribution Guidelines](#contribution-guidelines) |
| 8 | + - [Open a GitHub issue](#open-a-github-issue) |
| 9 | + - [Fork the repository on GitHub](#fork-the-repository-on-github) |
| 10 | + - [Install the pre-commit hooks](#install-the-pre-commit-hooks) |
| 11 | + - [Update the documentation](#update-the-documentation) |
| 12 | + - [Update the tests](#update-the-tests) |
| 13 | + - [Update the code](#update-the-code) |
| 14 | + - [Create a pull request](#create-a-pull-request) |
| 15 | + - [Merge and release](#merge-and-release) |
| 16 | + |
| 17 | +## Open a GitHub issue |
| 18 | + |
| 19 | +For bug reports or requests, please submit your issue in the appropriate repository. |
| 20 | + |
| 21 | +We advise that you open an issue and ask the |
| 22 | +[CODEOWNERS] and community prior to starting a contribution. |
| 23 | +This is your chance to ask questions and receive feedback before |
| 24 | +writing (potentially wrong) code. We value the direct contact with our community |
| 25 | +a lot, so don't hesitate to ask any questions. |
| 26 | + |
| 27 | +## Fork the repository on GitHub |
| 28 | + |
| 29 | +[Fork] the repository into your own GitHub account and [create a new branch] as |
| 30 | +described in the [GitHub Flow]. |
| 31 | + |
| 32 | +## Install the pre-commit hooks |
| 33 | + |
| 34 | +If the repository you're working on ships with a |
| 35 | +[`.pre-commit-config.yaml`][pre-commit-file], |
| 36 | +make sure the necessary hooks have been installed before you begin working |
| 37 | +(e.g. a `pre-commit install`). |
| 38 | + |
| 39 | +## Update the documentation |
| 40 | + |
| 41 | +We encourage you to update the documentation before writing any code (please see |
| 42 | +[Readme Driven Development]. This ensures the |
| 43 | +documentation stays up to date and allows you to think through the problem fully before you begin implementing any |
| 44 | +changes. |
| 45 | + |
| 46 | +## Update the tests |
| 47 | + |
| 48 | +We also recommend updating the automated tests before updating any code |
| 49 | +(see [Test Driven Development](https://en.wikipedia.org/wiki/Test-driven_development)). |
| 50 | + |
| 51 | +That means that you should add or update a test case, run all tests and verify |
| 52 | +that the new test fails with a clear error message and then start implementing |
| 53 | +the code changes to get that test to pass. |
| 54 | + |
| 55 | +The test folder in every repository will have documentation on how to run the |
| 56 | +tests locally. |
| 57 | + |
| 58 | +## Update the code |
| 59 | + |
| 60 | +At this point, make your code changes and constantly test again your new test case to make sure that everything working |
| 61 | +properly. Do [commit] early and often and make useful commit messages. |
| 62 | + |
| 63 | +If a backwards incompatible change cannot be avoided, please make sure to call that out when you submit a pull request, |
| 64 | +explaining why the change is absolutely necessary. |
| 65 | + |
| 66 | +## Create a pull request |
| 67 | + |
| 68 | +[Create a pull request] with your changes. |
| 69 | +Please make sure to include the following: |
| 70 | + |
| 71 | +1. A description of the change, including a link to your GitHub issue. |
| 72 | +1. Any notes on backwards incompatibility or downtime. |
| 73 | + |
| 74 | +## Merge and release |
| 75 | + |
| 76 | +The [CODEOWNERS] of the repository will review your code and provide feedback. |
| 77 | +If everything looks good, they will merge the code and release a new version while following the principles of [Semantic Versioning (SemVer)]. |
| 78 | + |
| 79 | +<!-- References --> |
| 80 | + |
| 81 | +[github flow]: https://guides.github.com/introduction/flow/ |
| 82 | +[codeowners]: https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners |
| 83 | +[fork]: https://help.github.com/en/github/getting-started-with-github/fork-a-repo |
| 84 | +[create a new branch]: https://guides.github.com/introduction/flow/ |
| 85 | +[readme driven development]: https://tom.preston-werner.com/2010/08/23/readme-driven-development.html |
| 86 | +[commit]: https://help.github.com/en/desktop/contributing-to-projects/committing-and-reviewing-changes-to-your-project |
| 87 | +[create a pull request]: https://help.github.com/articles/creating-a-pull-request/ |
| 88 | +[semantic versioning (semver)]: https://semver.org/ |
| 89 | +[pull requests]: https://github.com/mineiros-io/terraform-github-repository/pulls |
| 90 | +[pre-commit-file]: https://github.com/mineiros-io/terraform-github-repository/blob/main/.pre-commit-config.yaml |
0 commit comments