From 5510e27c21c0e4fca5939e67a84de8a9c0e89230 Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Tue, 11 Aug 2026 14:45:57 +1000 Subject: [PATCH] docs: require signed commits, rename CONTRIBUTE.md to CONTRIBUTING.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two changes to the contributor guidelines: 1. Add a "Signing Your Commits" section. All commits in a PR must be cryptographically signed. Covers SSH and GPG setup, the GitHub key-type and email-matching gotchas that produce an Unverified badge, and how to retroactively sign commits that were already pushed. 2. Rename the file to CONTRIBUTING.md. GitHub only surfaces the "Contributing guidelines" prompt on new issues and PRs for that exact filename, so third-party contributors were never shown this document — which is a large part of why unsigned PRs arrive. Inbound links in README.md, packages/stack/README.md, and the target list in scripts/lint-no-dead-package-paths.mjs updated to match. --- CONTRIBUTE.md => CONTRIBUTING.md | 66 ++++++++++++++++++++++++++ README.md | 4 +- packages/stack/README.md | 4 +- scripts/lint-no-dead-package-paths.mjs | 2 +- 4 files changed, 71 insertions(+), 5 deletions(-) rename CONTRIBUTE.md => CONTRIBUTING.md (74%) diff --git a/CONTRIBUTE.md b/CONTRIBUTING.md similarity index 74% rename from CONTRIBUTE.md rename to CONTRIBUTING.md index 44a2cd535..c08c7e95f 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTING.md @@ -95,6 +95,72 @@ Then navigate to one of the examples in `examples/` and follow its README. 5. **Add a changeset** if your change affects a published package's public behaviour (see below). +6. **Sign your commits** — every commit in a pull request must be signed (see below). + +## Signing Your Commits + +**All commits must be cryptographically signed.** This is a hard requirement: pull +requests containing unsigned commits will not be merged. Signing ties each commit to +a verified identity, which matters for a repository whose packages ship as +dependencies into other people's applications — an unsigned commit is an unattributable +change in a supply chain. + +GitHub shows a **Verified** badge next to signed commits. If a commit in your PR +doesn't have one, it needs to be re-signed. + +### Set up signing + +You can sign with SSH (simplest if you already push over SSH) or GPG. + +**SSH signing** (Git >= 2.34): + +```bash +git config --global gpg.format ssh +git config --global user.signingkey ~/.ssh/id_ed25519.pub +git config --global commit.gpgsign true +``` + +Then add the same public key to your GitHub account as a **Signing Key** +(Settings → SSH and GPG keys → New SSH key → key type "Signing Key"). A key +registered only as an authentication key will not produce a Verified badge. + +**GPG signing:** + +```bash +gpg --full-generate-key # if you don't already have a key +gpg --list-secret-keys --keyid-format=long # copy the key ID +git config --global user.signingkey +git config --global commit.gpgsign true +``` + +Then export the public key (`gpg --armor --export `) and add it to GitHub +under Settings → SSH and GPG keys → New GPG key. + +The email on your signing key must match the email in your Git config and be a +verified email on your GitHub account, or GitHub will mark the commit +**Unverified** rather than **Verified**. + +Full instructions: [GitHub — signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). + +### Fixing unsigned commits + +If you've already pushed unsigned commits, sign them retroactively and force-push +to your branch: + +```bash +# Sign the last N commits (replace N with the number of commits in your PR) +git rebase --exec 'git commit --amend --no-edit -S' -i HEAD~N + +# Or sign every commit on your branch relative to main +git rebase --exec 'git commit --amend --no-edit -S' main + +git push --force-with-lease +``` + +Force-pushing rewrites history on your branch. Only do this on your own PR branch, +never on `main`, and check with the maintainers first if anyone else has based work +on your branch. + ## Publish Process (via Changesets) We use [**Changesets**](https://github.com/changesets/changesets) to manage versioning and publication to npm. diff --git a/README.md b/README.md index 008155c61..060776f47 100644 --- a/README.md +++ b/README.md @@ -353,7 +353,7 @@ npm install @cipherstash/stack # or: yarn / pnpm / bun add @cipherstash/stack ## Contributing · Security · License -Contributions are welcome — see [CONTRIBUTE.md][contribute]. For our security policy and responsible +Contributions are welcome — see [CONTRIBUTING.md][contribute]. For our security policy and responsible disclosure, see [SECURITY.md][security-policy]. [MIT licensed][license]. @@ -384,6 +384,6 @@ disclosure, see [SECURITY.md][security-policy]. [MIT licensed][license]. [eql]: https://github.com/cipherstash/encrypt-query-language [discord]: https://discord.gg/5qwXUFb6PB [examples]: https://github.com/cipherstash/stack/tree/main/examples -[contribute]: https://github.com/cipherstash/stack/blob/main/CONTRIBUTE.md +[contribute]: https://github.com/cipherstash/stack/blob/main/CONTRIBUTING.md [security-policy]: https://github.com/cipherstash/stack/blob/main/SECURITY.md [license]: https://github.com/cipherstash/stack/blob/main/LICENSE.md diff --git a/packages/stack/README.md b/packages/stack/README.md index 008155c61..060776f47 100644 --- a/packages/stack/README.md +++ b/packages/stack/README.md @@ -353,7 +353,7 @@ npm install @cipherstash/stack # or: yarn / pnpm / bun add @cipherstash/stack ## Contributing · Security · License -Contributions are welcome — see [CONTRIBUTE.md][contribute]. For our security policy and responsible +Contributions are welcome — see [CONTRIBUTING.md][contribute]. For our security policy and responsible disclosure, see [SECURITY.md][security-policy]. [MIT licensed][license]. @@ -384,6 +384,6 @@ disclosure, see [SECURITY.md][security-policy]. [MIT licensed][license]. [eql]: https://github.com/cipherstash/encrypt-query-language [discord]: https://discord.gg/5qwXUFb6PB [examples]: https://github.com/cipherstash/stack/tree/main/examples -[contribute]: https://github.com/cipherstash/stack/blob/main/CONTRIBUTE.md +[contribute]: https://github.com/cipherstash/stack/blob/main/CONTRIBUTING.md [security-policy]: https://github.com/cipherstash/stack/blob/main/SECURITY.md [license]: https://github.com/cipherstash/stack/blob/main/LICENSE.md diff --git a/scripts/lint-no-dead-package-paths.mjs b/scripts/lint-no-dead-package-paths.mjs index 321b30e04..9d3b52ed3 100644 --- a/scripts/lint-no-dead-package-paths.mjs +++ b/scripts/lint-no-dead-package-paths.mjs @@ -19,7 +19,7 @@ const TARGETS = process.argv.slice(2).length 'CLAUDE.md', 'README.md', 'SECURITY.md', - 'CONTRIBUTE.md', + 'CONTRIBUTING.md', 'docs', '.github', 'skills',