From 9661dfd18d0fb3ec38971367c0b1efc6c09a8f00 Mon Sep 17 00:00:00 2001 From: lukasmetzner Date: Tue, 26 May 2026 14:08:05 +0200 Subject: [PATCH 01/12] feat: add contribution guidelines --- CONTRIBUTING.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c25a92b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,96 @@ +# Contribution Guideline + +## Code of Conduct + +This project follows the core values of the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/3/0/code_of_conduct/). + +## Reporting a bug + +1. **Check first** that the bug isn't already filed — search both open and + closed issues. If you find a match, add a 👍 reaction or a comment with new + information rather than opening a duplicate. +2. **Use the issue template** for the relevant repo. + +## Proposing a change + +The kinds of pull requests we welcome: + +- **Bug fixes** for clearly identified bugs. The PR description should explain + what is being fixed and how to verify it. A regression test is expected. +- **New features** that solve a use case shared by a meaningful portion of users. + **Please open an issue first** and wait for a maintainer to confirm the direction before writing code. +- **Chores**: typos, comment clarifications. + Multiple typo or comment fixes can be combined into a single PR. + +What we'll generally **decline**: + +- Stylistic refactors that don't improve performance, correctness, or + testability. Code style is subjective and large diffs make `git blame` worse. + We're happy to accept small, principled cleanups alongside other work. +- Changes which result in a breaking change. +- "Drive-by" PRs where the contributor isn't available to address review + comments. + +## Pull request guidelines + +- **One concern per PR.** Smaller PRs get faster reviews. +- **Tests are required** for bug fixes (regression test) and new features + (coverage of the new path). +- **CI must be green** before a PR is merged. If a CI failure looks unrelated + to your change, comment on the PR rather than force-pushing — a maintainer + will have a look. - ⚠️ 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. +- **Allow edits from maintainers** when you open the PR, so we can rebase or + make small fixups directly. +- **Don't force-push** after a maintainer has started reviewing. Push new + commits; we squash on merge. +- **PR titles** should follow the [Conventional Commits](https://www.conventionalcommits.org/) pattern. See [Commit messages](#commit-messages) for more details. +- **Update the PR title and body** if the change drifts during review — the + title becomes the squash-merge commit message. + +### Commit messages + +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. + +``` +(): + + + + +``` + +Common types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `ci`, `build`. +A `feat:` triggers a minor release, a `fix:` triggers a patch release. + +Examples: + +- `feat(server-type): add support for ARM64 server types` +- `fix(load-balancer): retry transient 503s from the API` +- `docs: clarify token scopes in README` + +## AI / LLM policy + +You may use AI assistants when contributing, subject to all the following: + +1. **Disclose** in the PR description (or issue) that you used an AI tool, and + which one. One short line is enough. +2. **You are accountable.** You must understand every change you submit well + enough to explain it, defend it in review, and revise it without further AI + help if the reviewer asks. PRs from contributors who can't engage with + review comments will be closed. +3. **Submitted by a human.** PRs must come from a real, human-owned GitHub + account. We don't accept submissions from bot accounts or unattended agents. +4. **Quality bar is unchanged.** AI-generated boilerplate, half-finished code, + plausible-but-wrong fixes, or hallucinated APIs will be closed. +5. **Cap on open AI-assisted PRs.** Contributors may have at most + two open AI-assisted PR(s) at a time. This protects review + capacity. Maintainers are not subject to this cap. + +## Licensing + +By submitting a contribution, you agree that it is licensed under the same +licence as the repository you're contributing to. See each repo's `LICENSE` +file. + +Thanks for contributing. If something in these guidelines is unclear or seems +to be missing, please open an issue or PR — they apply to themselves. From e3d10bacb1fbcaf352a19b4207856e677352683c Mon Sep 17 00:00:00 2001 From: lukasmetzner Date: Tue, 26 May 2026 14:16:06 +0200 Subject: [PATCH 02/12] fix: bullet point list on same line --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c25a92b..5852eda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,8 @@ What we'll generally **decline**: (coverage of the new path). - **CI must be green** before a PR is merged. If a CI failure looks unrelated to your change, comment on the PR rather than force-pushing — a maintainer - will have a look. - ⚠️ 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. + will have a look. + - ⚠️ 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. - **Allow edits from maintainers** when you open the PR, so we can rebase or make small fixups directly. - **Don't force-push** after a maintainer has started reviewing. Push new From 365445eae09eb28a3040e9642cff49cc97e30177 Mon Sep 17 00:00:00 2001 From: lukasmetzner Date: Tue, 26 May 2026 14:20:06 +0200 Subject: [PATCH 03/12] fix: PR title requirements --- CONTRIBUTING.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5852eda..a266d52 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,9 +44,7 @@ What we'll generally **decline**: make small fixups directly. - **Don't force-push** after a maintainer has started reviewing. Push new commits; we squash on merge. -- **PR titles** should follow the [Conventional Commits](https://www.conventionalcommits.org/) pattern. See [Commit messages](#commit-messages) for more details. -- **Update the PR title and body** if the change drifts during review — the - title becomes the squash-merge commit message. +- **PR 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. ### Commit messages From ff50a891d917d5a466590a1e461dabd75c0e9c7c Mon Sep 17 00:00:00 2001 From: Lukas Metzner Date: Tue, 26 May 2026 14:34:59 +0200 Subject: [PATCH 04/12] docs: apply suggestions Co-authored-by: Jonas L. --- CONTRIBUTING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a266d52..4f9a030 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,18 +9,18 @@ This project follows the core values of the [Contributor Covenant Code of Conduc 1. **Check first** that the bug isn't already filed — search both open and closed issues. If you find a match, add a 👍 reaction or a comment with new information rather than opening a duplicate. -2. **Use the issue template** for the relevant repo. +2. **Use the issue template** when opening an issue. ## Proposing a change The kinds of pull requests we welcome: -- **Bug fixes** for clearly identified bugs. The PR description should explain +- **Fixes** for clearly identified bugs. The pull request description must explain what is being fixed and how to verify it. A regression test is expected. - **New features** that solve a use case shared by a meaningful portion of users. **Please open an issue first** and wait for a maintainer to confirm the direction before writing code. - **Chores**: typos, comment clarifications. - Multiple typo or comment fixes can be combined into a single PR. + Multiple typos or comment fixes can be combined into a single pull request. What we'll generally **decline**: @@ -28,12 +28,12 @@ What we'll generally **decline**: testability. Code style is subjective and large diffs make `git blame` worse. We're happy to accept small, principled cleanups alongside other work. - Changes which result in a breaking change. -- "Drive-by" PRs where the contributor isn't available to address review +- "Drive-by" pull requests where the contributor isn't available to address review comments. ## Pull request guidelines -- **One concern per PR.** Smaller PRs get faster reviews. +- **One concern per pull request.** Smaller pull requests get faster reviews. - **Tests are required** for bug fixes (regression test) and new features (coverage of the new path). - **CI must be green** before a PR is merged. If a CI failure looks unrelated @@ -44,7 +44,7 @@ What we'll generally **decline**: make small fixups directly. - **Don't force-push** after a maintainer has started reviewing. Push new commits; we squash on merge. -- **PR 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. +- **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. ### Commit messages @@ -88,7 +88,7 @@ You may use AI assistants when contributing, subject to all the following: ## Licensing By submitting a contribution, you agree that it is licensed under the same -licence as the repository you're contributing to. See each repo's `LICENSE` +licence as the repository you're contributing to. See each repository's `LICENSE` file. Thanks for contributing. If something in these guidelines is unclear or seems From 3869071485de2c34fd5a9c848a8afc6e40883e6d Mon Sep 17 00:00:00 2001 From: lukasmetzner Date: Tue, 26 May 2026 14:37:00 +0200 Subject: [PATCH 05/12] fix: ci errors must be fixed --- CONTRIBUTING.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f9a030..e485264 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,9 +36,7 @@ What we'll generally **decline**: - **One concern per pull request.** Smaller pull requests get faster reviews. - **Tests are required** for bug fixes (regression test) and new features (coverage of the new path). -- **CI must be green** before a PR is merged. If a CI failure looks unrelated - to your change, comment on the PR rather than force-pushing — a maintainer - will have a look. +- **Ensure you fix all errors** once the CI run has been approved by a maintainer. - ⚠️ 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. - **Allow edits from maintainers** when you open the PR, so we can rebase or make small fixups directly. From c99e286489d6dcd2e64bd1b8ba6b39d39a7bdaed Mon Sep 17 00:00:00 2001 From: lukasmetzner Date: Tue, 26 May 2026 14:38:40 +0200 Subject: [PATCH 06/12] fix: clear up ai assistant requirements --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e485264..2847c0e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,7 +67,7 @@ Examples: ## AI / LLM policy -You may use AI assistants when contributing, subject to all the following: +You may use AI assistants when contributing, provided every one of the following is met: 1. **Disclose** in the PR description (or issue) that you used an AI tool, and which one. One short line is enough. From 876b1fe6c32998380d0000ebc4a47d602b9234e3 Mon Sep 17 00:00:00 2001 From: jo Date: Wed, 27 May 2026 10:17:07 +0200 Subject: [PATCH 07/12] style: wording about reporter CI errors --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2847c0e..7cae40e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ What we'll generally **decline**: - **One concern per pull request.** Smaller pull requests get faster reviews. - **Tests are required** for bug fixes (regression test) and new features (coverage of the new path). -- **Ensure you fix all errors** once the CI run has been approved by a maintainer. +- **Ensure you fix all errors** reported by our CI. Note that CI runs have to be approved by a maintainer. - ⚠️ 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. - **Allow edits from maintainers** when you open the PR, so we can rebase or make small fixups directly. From b24227ea41878eed4c209e18b9b8003b0154d165 Mon Sep 17 00:00:00 2001 From: jo Date: Wed, 27 May 2026 10:19:35 +0200 Subject: [PATCH 08/12] style: PR => pull request --- CONTRIBUTING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7cae40e..c81af4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ What we'll generally **decline**: (coverage of the new path). - **Ensure you fix all errors** reported by our CI. Note that CI runs have to be approved by a maintainer. - ⚠️ 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. -- **Allow edits from maintainers** when you open the PR, so we can rebase or +- **Allow edits from maintainers** when you open the pull request, so we can rebase or make small fixups directly. - **Don't force-push** after a maintainer has started reviewing. Push new commits; we squash on merge. @@ -69,18 +69,18 @@ Examples: You may use AI assistants when contributing, provided every one of the following is met: -1. **Disclose** in the PR description (or issue) that you used an AI tool, and +1. **Disclose** in the pull request description (or issue) that you used an AI tool, and which one. One short line is enough. 2. **You are accountable.** You must understand every change you submit well enough to explain it, defend it in review, and revise it without further AI - help if the reviewer asks. PRs from contributors who can't engage with + help if the reviewer asks. pull requests from contributors who can't engage with review comments will be closed. -3. **Submitted by a human.** PRs must come from a real, human-owned GitHub +3. **Submitted by a human.** pull requests must come from a real, human-owned GitHub account. We don't accept submissions from bot accounts or unattended agents. 4. **Quality bar is unchanged.** AI-generated boilerplate, half-finished code, plausible-but-wrong fixes, or hallucinated APIs will be closed. -5. **Cap on open AI-assisted PRs.** Contributors may have at most - two open AI-assisted PR(s) at a time. This protects review +5. **Cap on open AI-assisted pull requests.** Contributors may have at most + two open AI-assisted pull request(s) at a time. This protects review capacity. Maintainers are not subject to this cap. ## Licensing @@ -90,4 +90,4 @@ licence as the repository you're contributing to. See each repository's `LICENSE file. Thanks for contributing. If something in these guidelines is unclear or seems -to be missing, please open an issue or PR — they apply to themselves. +to be missing, please open an issue or pull request — they apply to themselves. From f46528dee92219cde30f425a71ea880def9f8207 Mon Sep 17 00:00:00 2001 From: jo Date: Wed, 27 May 2026 10:21:19 +0200 Subject: [PATCH 09/12] style: update title and add friendly intro --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c81af4b..9eb3a2d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,6 @@ -# Contribution Guideline +# Contributing + +First off, thanks for taking the time to contribute! ❤️ ## Code of Conduct From c4f7ec7f560ffc711393d5b80c7b04582cac5b96 Mon Sep 17 00:00:00 2001 From: lukasmetzner Date: Wed, 27 May 2026 10:33:51 +0200 Subject: [PATCH 10/12] fix: typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9eb3a2d..2d5be32 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,7 +75,7 @@ You may use AI assistants when contributing, provided every one of the following which one. One short line is enough. 2. **You are accountable.** You must understand every change you submit well enough to explain it, defend it in review, and revise it without further AI - help if the reviewer asks. pull requests from contributors who can't engage with + help if the reviewer asks. Pull requests from contributors who can't engage with review comments will be closed. 3. **Submitted by a human.** pull requests must come from a real, human-owned GitHub account. We don't accept submissions from bot accounts or unattended agents. From 5ff7f85b3e4934f33950b225a892bc63ec2a3986 Mon Sep 17 00:00:00 2001 From: jo Date: Wed, 27 May 2026 10:34:31 +0200 Subject: [PATCH 11/12] style: typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2d5be32..c4f8830 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,7 +88,7 @@ You may use AI assistants when contributing, provided every one of the following ## Licensing By submitting a contribution, you agree that it is licensed under the same -licence as the repository you're contributing to. See each repository's `LICENSE` +license as the repository you're contributing to. See each repository's `LICENSE` file. Thanks for contributing. If something in these guidelines is unclear or seems From 4d87fb436bc695c5b07845d5b25e7ba14321b062 Mon Sep 17 00:00:00 2001 From: lukasmetzner Date: Wed, 27 May 2026 10:38:37 +0200 Subject: [PATCH 12/12] style: make ai policy an unordered list --- CONTRIBUTING.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c4f8830..794c9a6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,19 +71,19 @@ Examples: You may use AI assistants when contributing, provided every one of the following is met: -1. **Disclose** in the pull request description (or issue) that you used an AI tool, and - which one. One short line is enough. -2. **You are accountable.** You must understand every change you submit well - enough to explain it, defend it in review, and revise it without further AI - help if the reviewer asks. Pull requests from contributors who can't engage with - review comments will be closed. -3. **Submitted by a human.** pull requests must come from a real, human-owned GitHub - account. We don't accept submissions from bot accounts or unattended agents. -4. **Quality bar is unchanged.** AI-generated boilerplate, half-finished code, - plausible-but-wrong fixes, or hallucinated APIs will be closed. -5. **Cap on open AI-assisted pull requests.** Contributors may have at most - two open AI-assisted pull request(s) at a time. This protects review - capacity. Maintainers are not subject to this cap. +- **Disclose** in the pull request description (or issue) that you used an AI tool, and + which one. One short line is enough. +- **You are accountable.** You must understand every change you submit well + enough to explain it, defend it in review, and revise it without further AI + help if the reviewer asks. Pull requests from contributors who can't engage with + review comments will be closed. +- **Submitted by a human.** pull requests must come from a real, human-owned GitHub + account. We don't accept submissions from bot accounts or unattended agents. +- **Quality bar is unchanged.** AI-generated boilerplate, half-finished code, + plausible-but-wrong fixes, or hallucinated APIs will be closed. +- **Cap on open AI-assisted pull requests.** Contributors may have at most + two open AI-assisted pull request(s) at a time. This protects review + capacity. Maintainers are not subject to this cap. ## Licensing