diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index dd08e0c..4922472 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -75,7 +75,7 @@ source (vendor KB, Event ID, registry key) where you can. 4. Run the relevant checks locally (`just` `prove`, `just` `abi-check`, `cargo` `test`, `zig` `build` `test`). -5. Sign your commits (SSH or GPG). +5. Sign your commits with SSH (see Signed commits). 6. Follow [Conventional Commits](https://www.conventionalcommits.org/). @@ -90,3 +90,20 @@ documentation and prose. This is a sole-maintainer project; the maintainer reviews all contributions. Significant or structural changes should be discussed in an issue first (see GOVERNANCE.adoc). + +## Signed commits + +Every commit that reaches the default branch must be signed; a ruleset refuses +unsigned pushes. Estate policy: +[SIGNING-POLICY](https://github.com/hyperpolymath/standards/blob/main/docs/SIGNING-POLICY.adoc). + +- **People and interactive agents** sign with an SSH key registered on GitHub + as a *signing* key (`gpg.format=ssh`, `user.signingkey=.pub`, + `commit.gpgsign=true`). The committer email must be verified on that account. +- **Apps, bots and workflows** never `git push` local commits. They write + through the API (`createCommitOnBranch` or the estate `signed-push` action) + so that GitHub signs each commit. +- Merge PRs with **squash**. The ruleset checks every commit on the PR branch, + not just the result, so one unsigned commit blocks the merge. Re-create such a + branch with signed commits (`git cherry-pick -S`) and open a new PR. + Rebase-merge replays commits unsigned and is disabled. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 246b5e2..60a6ad3 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -56,3 +56,20 @@ This root document exists because the estate docs gate `CONTRIBUTING.md`, `CONTRIBUTING.adoc`, or `3-practice/CONTRIBUTING.adoc` at the repository root. Estate documentation policy: AsciiDoc by default — see `hyperpolymath/standards`. + +== Signed commits + +Every commit that reaches the default branch must be signed; a ruleset refuses +unsigned pushes. Estate policy: +https://github.com/hyperpolymath/standards/blob/main/docs/SIGNING-POLICY.adoc[SIGNING-POLICY]. + +* **People and interactive agents** sign with an SSH key registered on GitHub + as a *signing* key (`gpg.format=ssh`, `user.signingkey=.pub`, + `commit.gpgsign=true`). The committer email must be verified on that account. +* **Apps, bots and workflows** never `git push` local commits. They write + through the API (`createCommitOnBranch` or the estate `signed-push` action) + so that GitHub signs each commit. +* Merge PRs with **squash**. The ruleset checks every commit on the PR branch, + not just the result, so one unsigned commit blocks the merge. Re-create such a + branch with signed commits (`git cherry-pick -S`) and open a new PR. + Rebase-merge replays commits unsigned and is disabled.