From 1be113aa35d36ff8c785744eccc5c25a6b000a10 Mon Sep 17 00:00:00 2001 From: Rein Krul Date: Mon, 18 May 2026 11:26:07 +0200 Subject: [PATCH 1/4] docs: add COLLABORATORS.md with contribution guidelines Covers small PRs, signed commits, Conventional Commits, code conventions, tests, code generation via makefile, and review etiquette (no force-push after review starts). Assisted by AI --- COLLABORATORS.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 COLLABORATORS.md diff --git a/COLLABORATORS.md b/COLLABORATORS.md new file mode 100644 index 0000000000..23f9f120dc --- /dev/null +++ b/COLLABORATORS.md @@ -0,0 +1,86 @@ +# Collaborating on nuts-node + +Thanks for your interest in contributing. This file is the short version of +how we work. For security issues, see [SECURITY.md](SECURITY.md) — please do +not file vulnerabilities as public issues or PRs. + +## Before you start + +- **Open an issue first** for anything non-trivial (new feature, behaviour + change, refactor that touches multiple packages). A 5-minute discussion + up front beats a rejected PR. +- For typos, doc fixes, and obvious bugs, skip straight to a PR. + +## Pull requests + +### Keep them small + +One concern per PR. A reviewer should be able to load the whole diff in their +head in a few minutes. Don't bundle refactors, renames, or "while I'm here" +cleanups with a feature or fix — land them as separate PRs. + +### Sign your commits + +All commits must be signed (GPG, SSH, or S/MIME). Branch protection +enforces this; unsigned commits cannot be merged. See +[git's documentation on signing](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) +or [GitHub's setup guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). + +### Commit messages + +We use [Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): +``` + +Examples from recent history: + +- `feat(crypto): accept RS256 in SupportedAlgorithms` +- `fix(auth/iam): enforce single authorization_details entry per call` +- `docs(auth/openid4vci): note follow-up to move URL validation to HTTPClient` +- `ci: move Go test pipeline from CircleCI to GitHub Actions` + +Common types: `feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`. + +Subjects are imperative ("add X", not "added X") and under ~72 chars. Put +the *why* in the PR description, not the commit message. + +## Code + +- **Match the surrounding code.** Naming, error handling, logging, test + style — follow the nearest neighbour (same file > same package > repo). + Don't introduce a new pattern when an existing one fits. +- **No drive-by refactors.** See "Keep them small" above. + +## Tests + +- New code needs tests. Bug fixes need a regression test that fails before + the fix. +- Run the full suite before pushing: `go test ./...`. +- Integration / e2e tests live under `e2e-tests/`. + +## Code generation + +When you change OpenAPI specs, mock interfaces, or other generated inputs, +regenerate via the `makefile` — don't invoke `oapi-codegen` / `mockgen` +directly: + +- `make gen-api` +- `make gen-mocks` +- `make run-generators` + +## Review + +- A maintainer from [`.github/CODEOWNERS`](.github/CODEOWNERS) needs to + approve before merge. +- CI must be green. Don't merge with red checks. +- Address review comments by pushing additional commits. +- **Do not rebase or force-push once review has started.** It throws away + GitHub's diff-since-last-review and forces reviewers to start over. Save + the rebase/squash for the merge. + +## Licence + +By contributing you agree your changes are licensed under the same terms as +the project (see [COPYING](COPYING)). From f1d79740d368bad66704504480ccf96fe1de0dde Mon Sep 17 00:00:00 2001 From: Rein Krul Date: Mon, 18 May 2026 11:29:06 +0200 Subject: [PATCH 2/4] docs: point existing contribute docs at COLLABORATORS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Avoid duplicating contribution guidance across README.rst, .github/README.md, and docs/pages/contribute.rst — each now links to COLLABORATORS.md. Assisted by AI --- .github/README.md | 1 + README.rst | 5 +++++ docs/pages/contribute.rst | 2 +- 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/README.md b/.github/README.md index 7e9a71672e..c7a63cdf06 100644 --- a/.github/README.md +++ b/.github/README.md @@ -8,6 +8,7 @@ Claude Code skill files (custom slash commands) for common maintenance tasks are ## For Contributors +- **[COLLABORATORS.md](../COLLABORATORS.md)** - How to contribute - **[CODEOWNERS](CODEOWNERS)** - Defines code ownership for automatic review assignment - **[dependabot.yml](dependabot.yml)** - Configuration for automated dependency updates - **[workflows/](workflows/)** - GitHub Actions workflow definitions diff --git a/README.rst b/README.rst index b01864c2d6..31d1448529 100644 --- a/README.rst +++ b/README.rst @@ -31,6 +31,11 @@ See the `documentation `_ for how t :target: https://join.slack.com/t/nuts-foundation/shared_invite/zt-19av5q5ur-5fNbZVIFGUw5vDKSy5mqCw :alt: Nuts Community on Slack +Contributing +^^^^^^^^^^^^ + +See `COLLABORATORS.md `_ for how to contribute. + For AI-agentic Maintainers ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/pages/contribute.rst b/docs/pages/contribute.rst index 68f64505f4..3330d5d582 100644 --- a/docs/pages/contribute.rst +++ b/docs/pages/contribute.rst @@ -2,4 +2,4 @@ Contribute ########## -If you want to contribute to any of the nuts foundation projects or to this documentation, please fork the correct project from `Github `_ and create a pull-request. +See `COLLABORATORS.md `_ for how to contribute to ``nuts-node``. From f033cf67364fd6c6f956b51f9eae64fa60d15e85 Mon Sep 17 00:00:00 2001 From: Rein Krul Date: Mon, 18 May 2026 11:31:38 +0200 Subject: [PATCH 3/4] docs: update README_template.rst (source for generated README.rst) README.rst is generated by 'rst_include include README_template.rst README.rst' (via 'make cli-docs'). Update the template so the generated file stays in sync with manual edits. Assisted by AI --- README_template.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README_template.rst b/README_template.rst index b2f71317c6..c23b372dbd 100644 --- a/README_template.rst +++ b/README_template.rst @@ -31,6 +31,11 @@ See the `documentation `_ for how t :target: https://join.slack.com/t/nuts-foundation/shared_invite/zt-19av5q5ur-5fNbZVIFGUw5vDKSy5mqCw :alt: Nuts Community on Slack +Contributing +^^^^^^^^^^^^ + +See `COLLABORATORS.md `_ for how to contribute. + For AI-agentic Maintainers ^^^^^^^^^^^^^^^^^^^^^^^^^^ From 4c9c29cf6d658605ac91f4354f406da5d21f8028 Mon Sep 17 00:00:00 2001 From: Rein Krul Date: Fri, 22 May 2026 10:33:53 +0200 Subject: [PATCH 4/4] docs(collaborators): add backwards-compatibility section Assisted by AI --- COLLABORATORS.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/COLLABORATORS.md b/COLLABORATORS.md index 23f9f120dc..72472faed5 100644 --- a/COLLABORATORS.md +++ b/COLLABORATORS.md @@ -11,6 +11,23 @@ not file vulnerabilities as public issues or PRs. up front beats a rejected PR. - For typos, doc fixes, and obvious bugs, skip straight to a PR. +## Backwards compatibility + +We don't accept breaking changes to public interfaces — HTTP APIs, +configuration (CLI flags, environment variables, `nuts.yaml`), observable +behaviour, and the Nuts network protocols. Breaking changes land only in a +new major version, which the maintainers plan. + +What counts as breaking and how it maps to version numbers is already +documented: + +- [API development](docs/pages/development/3-api.rst) — API versioning rules. +- [Releasing — Semantic versioning](docs/pages/development/2-releasing.rst) — + how "API" is scoped (it also covers config and network protocols) and + which version part a change bumps. + +If a change you need can't be made backwards compatible, open an issue first. + ## Pull requests ### Keep them small