|
| 1 | +--- |
| 2 | +template: main.html |
| 3 | +--- |
| 4 | + |
| 5 | +# Contributing Guide |
| 6 | + |
| 7 | +Welcome! We are delighted that you want to contribute to Iter8! 💖 |
| 8 | + |
| 9 | +As you get started, you are in the best position to give us feedback on areas of |
| 10 | +our project that we need help with including: |
| 11 | + |
| 12 | +* Problems found during setup of Iter8 |
| 13 | +* Gaps in our quick start guide or other tutorials and documentation |
| 14 | +* Bugs in our test and automation scripts |
| 15 | + |
| 16 | +If anything doesn't make sense, or doesn't work when you run it, please open a |
| 17 | +bug report and let us know! |
| 18 | + |
| 19 | +*** |
| 20 | + |
| 21 | +## Ways to Contribute |
| 22 | + |
| 23 | +We welcome many different types of contributions including: |
| 24 | + |
| 25 | +* [Iter8 documentation / tutorials](../tutorials) |
| 26 | +* New features |
| 27 | +* Builds, CI |
| 28 | +* Bug fixes |
| 29 | +* Web design for https://iter8.tools |
| 30 | +* Communications / social media / blog posts |
| 31 | +* Reviewing pull requests |
| 32 | + |
| 33 | +Not everything happens through a GitHub pull request. Please come to our |
| 34 | +[meetings](#come-to-meetings) or [contact us](../../../getting-started/help) and let's discuss how we can work together. |
| 35 | + |
| 36 | +*** |
| 37 | + |
| 38 | +## Come to meetings! |
| 39 | +Absolutely everyone is welcome to come to any of our meetings. You never need an |
| 40 | +invite to join us. In fact, we want you to join us, even if you don’t have |
| 41 | +anything you feel like you want to contribute. Just being there is enough! |
| 42 | + |
| 43 | +You can find out more about our meetings [here](../../../getting-started/help). You don’t have to turn on your video. The first time you come, introducing yourself is more than enough. |
| 44 | +Over time, we hope that you feel comfortable voicing your opinions, giving |
| 45 | +feedback on others’ ideas, and even sharing your own ideas, and experiences. |
| 46 | + |
| 47 | +*** |
| 48 | + |
| 49 | +## Find an Issue |
| 50 | + |
| 51 | +Iter8 issues are managed centrally [here](https://github.com/iter8-tools/iter8/issues). |
| 52 | + |
| 53 | +We have good first issues for new contributors and help wanted issues suitable |
| 54 | +for any contributor. Issued labeled **good first issue** have extra information to |
| 55 | +help you make your first contribution. Issues labeled **help wanted** are issues |
| 56 | +suitable for someone who isn't a core maintainer and is good to move onto after |
| 57 | +your first pull request. |
| 58 | + |
| 59 | +Sometimes there won’t be any issues with these labels. That’s ok! There is |
| 60 | +likely still something for you to work on. If you want to contribute but you |
| 61 | +don’t know where to start or can't find a suitable issue, you can reach out to us over the [Iter8 slack workspace](https://join.slack.com/t/iter8-tools/shared_invite/zt-awl2se8i-L0pZCpuHntpPejxzLicbmw) for help finding something to work on. |
| 62 | + |
| 63 | +Once you see an issue that you'd like to work on, please post a comment saying |
| 64 | +that you want to work on it. Something like "I want to work on this" is fine. |
| 65 | + |
| 66 | +*** |
| 67 | + |
| 68 | +## Ask for Help |
| 69 | + |
| 70 | +The best ways to reach us with a question when contributing is to ask on: |
| 71 | + |
| 72 | +* The original GitHub issue |
| 73 | +* `#development` channel in the [Iter8 slack workspace](https://join.slack.com/t/iter8-tools/shared_invite/zt-awl2se8i-L0pZCpuHntpPejxzLicbmw) |
| 74 | + |
| 75 | +<!-- ## Pull Request Lifecycle |
| 76 | +
|
| 77 | +**TODO** --> |
| 78 | +<!-- This is an optional section but we encourage you to think about your |
| 79 | +pull request process and help set expectations for both contributors and |
| 80 | +reviewers. |
| 81 | +
|
| 82 | +Instead of a fixed template, use these questions below as an exercise to uncover |
| 83 | +the unwritten rules and norms your project has for both reviewers and |
| 84 | +contributors. Using your answers, write a description of what a |
| 85 | +contributor can expect during their pull request. |
| 86 | +
|
| 87 | +* When should contributors start to submit a PR - when it’s ready for review or |
| 88 | + as a work-in-progress? |
| 89 | +* How do contributors signal that a PR is ready for review or that it’s not |
| 90 | + complete and still a work-in-progress? |
| 91 | +* When should the contributor should expect initial review? The follow-up |
| 92 | + reviews? |
| 93 | +* When and how should the author ping/bump when the pull request is ready for |
| 94 | + further review or appears stalled? |
| 95 | +* How to handle stuck pull requests that you can’t seem to get reviewed? |
| 96 | +* How to handle follow-up issues and pull requests? |
| 97 | +* What kind of pull requests do you prefer: small scope, incremental value or |
| 98 | + feature complete? |
| 99 | +* What should contributors do if they no longer want to follow-through with the |
| 100 | + PR? For example, will maintainers potentially refactor and use the code? |
| 101 | + Will maintainers close a PR if the contributor hasn’t responded in a specific |
| 102 | + timeframe? |
| 103 | +* Once a PR is merged, what is the process for it getting into the next release? |
| 104 | +* When does a contribution show up “live”? |
| 105 | +
|
| 106 | +Here are some examples from other projects: |
| 107 | + |
| 108 | +* https://porter.sh/src/CONTRIBUTING.md#the-life-of-a-pull-request |
| 109 | +
|
| 110 | +--> |
| 111 | + |
| 112 | +<!-- ## Development Environment Setup |
| 113 | +
|
| 114 | +**TODO** --> |
| 115 | +<!-- Provide enough information so that someone can find your project on |
| 116 | +the weekend and get set up, build the code, test it and submit a pull request |
| 117 | +successfully without having to ask any questions. If there is a one-off tool |
| 118 | +they need to install, of common error people run into, or useful script they |
| 119 | +should run, document it here. |
| 120 | +
|
| 121 | +Document any necessary tools, for example VS Code and recommended extensions. |
| 122 | +You don’t have to document the beginner’s guide to these tools, but how they |
| 123 | +are used within the scope of your project. |
| 124 | +
|
| 125 | +* How to get the source code |
| 126 | +* How to get any dependencies |
| 127 | +* How to build the source code |
| 128 | +* How to run the project locally |
| 129 | +* How to test the source code, unit and "integration" or "end-to-end" |
| 130 | +* How to generate and preview the documentation locally |
| 131 | +* Links to new user documentation videos and examples to get people started and |
| 132 | + understanding how to use the project |
| 133 | +
|
| 134 | +--> |
| 135 | +*** |
| 136 | + |
| 137 | +## Sign Your Commits |
| 138 | + |
| 139 | +Licensing is important to open source projects. It provides some assurances that |
| 140 | +the software will continue to be available based under the terms that the |
| 141 | +author(s) desired. We require that contributors sign off on commits submitted to |
| 142 | +our project's repositories. The [Developer Certificate of Origin |
| 143 | +(DCO)](https://developercertificate.org/) is a way to certify that you wrote and |
| 144 | +have the right to contribute the code you are submitting to the project. |
| 145 | + |
| 146 | +You sign-off by adding the following to your commit messages. Your sign-off must |
| 147 | +match the git user and email associated with the commit. |
| 148 | + |
| 149 | + This is my commit message |
| 150 | + |
| 151 | + Signed-off-by: Your Name <[email protected]> |
| 152 | + |
| 153 | +Git has a `-s` command line option to do this automatically: |
| 154 | + |
| 155 | + git commit -s -m 'This is my commit message' |
| 156 | + |
| 157 | +If you forgot to do this and have not yet pushed your changes to the remote |
| 158 | +repository, you can amend your commit with the sign-off by running |
| 159 | + |
| 160 | + git commit --amend -s |
| 161 | + |
| 162 | +<!-- ## Pull Request Checklist |
| 163 | +
|
| 164 | +When you submit your pull request, or you push new commits to it, our automated |
| 165 | +systems will run some checks on your new code. We require that your pull request |
| 166 | +passes these checks, but we also have more criteria than just that before we can |
| 167 | +accept and merge it. We recommend that you check the following things locally |
| 168 | +before you submit your code: |
| 169 | +
|
| 170 | +**TODO** --> |
| 171 | +<!-- list both the automated and any manual checks performed by reviewers, it |
| 172 | +is very helpful when the validations are automated in a script for example in a |
| 173 | +Makefile target. Below is an example of a checklist: |
| 174 | +
|
| 175 | +* It passes tests: run the following command to run all of the tests locally: |
| 176 | + `make build test lint` |
| 177 | +* Impacted code has new or updated tests |
| 178 | +* Documentation created/updated |
| 179 | +* We use [Azure DevOps, GitHub Actions, CircleCI] to test all pull |
| 180 | + requests. We require that all tests succeed on a pull request before it is merged. |
| 181 | +
|
| 182 | +--> |
0 commit comments