|
| 1 | +# How to contribute |
| 2 | + |
| 3 | +## Communication |
| 4 | + |
| 5 | +- Issues: [GitHub](https://github.com/authzed/docs/issues) |
| 6 | +- Email: [Google Groups](https://groups.google.com/g/authzed-oss) |
| 7 | +- Discord: [Zanzibar Discord](https://authzed.com/discord) |
| 8 | + |
| 9 | +All communication must follow our [Code of Conduct]. |
| 10 | + |
| 11 | +[Code of Conduct]: CODE-OF-CONDUCT.md |
| 12 | + |
| 13 | +## Creating issues |
| 14 | + |
| 15 | +If any part of the project has a bug or documentation mistakes, please let us know by opening an issue. |
| 16 | +All bugs and mistakes are considered very seriously, regardless of complexity. |
| 17 | + |
| 18 | +Before creating an issue, please check that an issue reporting the same problem does not already exist. |
| 19 | +To make the issue accurate and easy to understand, please try to create issues that are: |
| 20 | + |
| 21 | +- Unique -- do not duplicate existing bug report. |
| 22 | + Duplicate bug reports will be closed. |
| 23 | +- Specific -- include as much details as possible: which version, what environment, what configuration, etc. |
| 24 | +- Reproducible -- include the steps to reproduce the problem. |
| 25 | + Some issues might be hard to reproduce, so please do your best to include the steps that might lead to the problem. |
| 26 | +- Isolated -- try to isolate and reproduce the bug with minimum dependencies. |
| 27 | + It would significantly slow down the speed to fix a bug if too many dependencies are involved in a bug report. |
| 28 | + Debugging external systems that rely on this project is out of scope, but guidance or help using the project itself is fine. |
| 29 | +- Scoped -- one bug per report. |
| 30 | + Do not follow up with another bug inside one report. |
| 31 | + |
| 32 | +It may be worthwhile to read [Elika Etemad’s article on filing good bug reports][filing-good-bugs] before creating a bug report. |
| 33 | + |
| 34 | +Maintainers might ask for further information to resolve an issue. |
| 35 | + |
| 36 | +[filing-good-bugs]: http://fantasai.inkedblade.net/style/talks/filing-good-bugs/ |
| 37 | + |
| 38 | +## Contribution flow |
| 39 | + |
| 40 | +This is a rough outline of what a contributor's workflow looks like: |
| 41 | + |
| 42 | +- Create an issue |
| 43 | +- Fork the project |
| 44 | +- Create a [feature branch] |
| 45 | +- Push changes to your branch |
| 46 | +- Submit a pull request |
| 47 | +- Respond to feedback from project maintainers |
| 48 | + |
| 49 | +Creating new issues is one of the best ways to contribute. |
| 50 | +You have no obligation to offer a solution or code to fix an issue that you open. |
| 51 | +If you do decide to try and contribute something, please submit an issue first so that a discussion can occur to avoid any wasted efforts. |
| 52 | + |
| 53 | +[feature branch]: https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow |
| 54 | + |
| 55 | +## Legal requirements |
| 56 | + |
| 57 | +In order to protect both you and ourselves, all commits will require an explicit sign-off that acknowledges the [DCO]. |
| 58 | + |
| 59 | +Sign-off commits end with the following line: |
| 60 | + |
| 61 | +```git |
| 62 | +Signed-off-by: Random J Developer <[email protected]> |
| 63 | +``` |
| 64 | + |
| 65 | +This can be done by using the `--signoff` (or `-s` for short) git flag to append this automatically to your commit message. |
| 66 | +If you have already authored a commit that is missing the signed-off, you can amend or rebase your commits and force push them to GitHub. |
| 67 | + |
| 68 | +[DCO]: /DCO |
0 commit comments