|
| 1 | +# Contributing |
| 2 | + |
| 3 | +First off, thanks for taking the time to contribute! ❤️ |
| 4 | + |
| 5 | +## Code of Conduct |
| 6 | + |
| 7 | +This project follows the core values of the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/3/0/code_of_conduct/). |
| 8 | + |
| 9 | +## Reporting a bug |
| 10 | + |
| 11 | +1. **Check first** that the bug isn't already filed — search both open and |
| 12 | + closed issues. If you find a match, add a 👍 reaction or a comment with new |
| 13 | + information rather than opening a duplicate. |
| 14 | +2. **Use the issue template** when opening an issue. |
| 15 | + |
| 16 | +## Proposing a change |
| 17 | + |
| 18 | +The kinds of pull requests we welcome: |
| 19 | + |
| 20 | +- **Fixes** for clearly identified bugs. The pull request description must explain |
| 21 | + what is being fixed and how to verify it. A regression test is expected. |
| 22 | +- **New features** that solve a use case shared by a meaningful portion of users. |
| 23 | + **Please open an issue first** and wait for a maintainer to confirm the direction before writing code. |
| 24 | +- **Chores**: typos, comment clarifications. |
| 25 | + Multiple typos or comment fixes can be combined into a single pull request. |
| 26 | + |
| 27 | +What we'll generally **decline**: |
| 28 | + |
| 29 | +- Stylistic refactors that don't improve performance, correctness, or |
| 30 | + testability. Code style is subjective and large diffs make `git blame` worse. |
| 31 | + We're happy to accept small, principled cleanups alongside other work. |
| 32 | +- Changes which result in a breaking change. |
| 33 | +- "Drive-by" pull requests where the contributor isn't available to address review |
| 34 | + comments. |
| 35 | + |
| 36 | +## Pull request guidelines |
| 37 | + |
| 38 | +- **One concern per pull request.** Smaller pull requests get faster reviews. |
| 39 | +- **Tests are required** for bug fixes (regression test) and new features |
| 40 | + (coverage of the new path). |
| 41 | +- **Ensure you fix all errors** reported by our CI. Note that CI runs have to be approved by a maintainer. |
| 42 | + - ⚠️ A lot of our e2e tests use the [tps-action](https://github.com/hetznercloud/tps-action). This action will fail for unauthorized users. Expect them to fail, if you are not part of our organization. A maintainer will run the e2e tests. If you decide on running them on your own costs, feel free to share the results. |
| 43 | +- **Allow edits from maintainers** when you open the pull request, so we can rebase or |
| 44 | + make small fixups directly. |
| 45 | +- **Don't force-push** after a maintainer has started reviewing. Push new |
| 46 | + commits; we squash on merge. |
| 47 | +- **Pull request titles** should follow the [Conventional Commits](https://www.conventionalcommits.org/) pattern because the title becomes the squash-merge commit message (see [Commit messages](#commit-messages) for details); update the title and body if the change drifts during review. |
| 48 | + |
| 49 | +### Commit messages |
| 50 | + |
| 51 | +We use [Conventional Commits](https://www.conventionalcommits.org/). The format matters because [releaser-pleaser](https://github.com/apricote/releaser-pleaser) generates our changelogs from it. |
| 52 | + |
| 53 | +``` |
| 54 | +<type>(<optional scope>): <short imperative summary, ≤72 chars> |
| 55 | +
|
| 56 | +<optional longer body explaining the why, wrapped at ~72 chars> |
| 57 | +
|
| 58 | +<optional footers, e.g. Fixes #123, BREAKING CHANGE: ...> |
| 59 | +``` |
| 60 | + |
| 61 | +Common types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `ci`, `build`. |
| 62 | +A `feat:` triggers a minor release, a `fix:` triggers a patch release. |
| 63 | + |
| 64 | +Examples: |
| 65 | + |
| 66 | +- `feat(server-type): add support for ARM64 server types` |
| 67 | +- `fix(load-balancer): retry transient 503s from the API` |
| 68 | +- `docs: clarify token scopes in README` |
| 69 | + |
| 70 | +## AI / LLM policy |
| 71 | + |
| 72 | +You may use AI assistants when contributing, provided every one of the following is met: |
| 73 | + |
| 74 | +- **Disclose** in the pull request description (or issue) that you used an AI tool, and |
| 75 | + which one. One short line is enough. |
| 76 | +- **You are accountable.** You must understand every change you submit well |
| 77 | + enough to explain it, defend it in review, and revise it without further AI |
| 78 | + help if the reviewer asks. Pull requests from contributors who can't engage with |
| 79 | + review comments will be closed. |
| 80 | +- **Submitted by a human.** pull requests must come from a real, human-owned GitHub |
| 81 | + account. We don't accept submissions from bot accounts or unattended agents. |
| 82 | +- **Quality bar is unchanged.** AI-generated boilerplate, half-finished code, |
| 83 | + plausible-but-wrong fixes, or hallucinated APIs will be closed. |
| 84 | +- **Cap on open AI-assisted pull requests.** Contributors may have at most |
| 85 | + two open AI-assisted pull request(s) at a time. This protects review |
| 86 | + capacity. Maintainers are not subject to this cap. |
| 87 | + |
| 88 | +## Licensing |
| 89 | + |
| 90 | +By submitting a contribution, you agree that it is licensed under the same |
| 91 | +license as the repository you're contributing to. See each repository's `LICENSE` |
| 92 | +file. |
| 93 | + |
| 94 | +Thanks for contributing. If something in these guidelines is unclear or seems |
| 95 | +to be missing, please open an issue or pull request — they apply to themselves. |
0 commit comments