From 36603d3a695291784537bc1aeca5f2118036814f Mon Sep 17 00:00:00 2001 From: Jason Karns Date: Mon, 13 Oct 2025 10:35:47 -0400 Subject: [PATCH 1/2] Improve the release process documentation --- .github/CONTRIBUTING.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index d0a9145..7822ca4 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,7 +2,21 @@ ## Releasing -From a clean working copy, run `npm version major|minor|patch|VERSION`. +From a clean working copy, run [`npm version major|minor|patch|VERSION`][npm-version]. This will bump the package version, commit, tag, and push. The tag-push event triggers the release workflow on GitHub. The workflow creates a GitHub Release from the tag and publishes to npm. + +It is preferred for these version commits and tags to be signed by git. This +not only aids with provenance, but the act of signing the tag also ensures +these release tags are [annotated tags][], not [lightweight tags][]. First be +sure git is [configured for signing][git signing]. Then either tell git to +sign _all_ tags with [`tag.gpgSign = true`][tag.gpgSign] (recommended), or +configure npm to sign its tags with [`sign-git-tag = true`][sign-git-tag]. + +[npm-version]: https://docs.npmjs.com/cli/v11/commands/npm-version +[annotated tags]: https://git-scm.com/book/en/v2/Git-Basics-Tagging#_annotated_tags +[lightweight tags]: https://git-scm.com/book/en/v2/Git-Basics-Tagging#_lightweight_tags +[git signing]: https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work +[tag.gpgSign]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-taggpgSign +[sign-git-tag]: https://docs.npmjs.com/cli/v11/using-npm/config#sign-git-tag From 21916fb262bb4c5ef161a9cd2127b1c1589283d9 Mon Sep 17 00:00:00 2001 From: Jason Karns Date: Mon, 13 Oct 2025 10:38:08 -0400 Subject: [PATCH 2/2] Move files for humans to non-hidden docs/ dir .github should be used for files targeted at machines and automation. the CONTRIBUTING file is special and needs to be in a location for github to find it (as there are various UI locations that file is linked and referenced). But the _primary_ consumer of that file should be humans, so let's surface it in a non-hidden directory. https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors --- {.github => docs}/CONTRIBUTING.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {.github => docs}/CONTRIBUTING.md (100%) diff --git a/.github/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 100% rename from .github/CONTRIBUTING.md rename to docs/CONTRIBUTING.md