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/COLLABORATORS.md b/COLLABORATORS.md new file mode 100644 index 0000000000..72472faed5 --- /dev/null +++ b/COLLABORATORS.md @@ -0,0 +1,103 @@ +# 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. + +## 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 + +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)). 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/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 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 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``.