Require one concern per commit, and a bump of its own

CONTRIBUTING.md

@@ -82,6 +82,23 @@ Every non-trivial commit gets a body, and the body answers **why**: what was
 wrong before, what breaks if it stays that way, what was measured. A commit
 whose body only rephrases its subject is a commit with no body.
 
+**One concern per commit, and a version bump is a concern of its own.** The
+subject is printed beside every file the commit touched, so a commit that
+carries four unrelated changes prints a sentence that is a quarter true of each
+of them. Releasing 0.0.2-beta.3 put *Carry the documentation corrections to npm
+and the site* on sixteen paths, including `CODE_OF_CONDUCT.md` and
+`.github/` — where it said nothing about what had changed. The subject was not
+the problem; folding a Code of Conduct contact, a CI job, a hook pattern and a
+version bump into one commit was.
+
+Split by what changed, not by when it shipped: the release ends with a bump
+that touches only the files a bump has to touch — `package.json`,
+`version.json`, `dist/`, `src/`, `types/`, `tokens.json`, `vocabulary.json`,
+`integrity.json`, the badges and pinned paths in the READMEs, `SECURITY.md`,
+`CHANGELOG.md`, `demo/`. Everything else is its own commit, made before it.
+`tools/release.sh` rejects a release whose final commit reaches outside that
+set.
+
 **Keep the subject under about 60 characters.** GitHub's file listing — the
 view that shows which commit last touched each file — truncates there, and a
 subject that survives it is the difference between a readable history and a

demo/index.html

@@ -336,8 +336,8 @@ <h3>Documentation</h3>
       <h3>Ecosystem</h3>
       <ul>
         <!-- Linked once the repository is public, listed until then: a footer
-             link to a repository that does not exist yet is a 404. All three
-             are out; none is on its host's own directory yet. -->
+             link to a repository that does not exist yet is a 404. Which name
+             sits in which list is asserted by tests/contract.test.mjs. -->
         <li>WordPress · <a href="https://github.com/jsrayorg/jsray-wp"><code>jsray-wp</code></a><span class="tag tag--beta">beta</span></li>
         <li>VS Code · <a href="https://github.com/jsrayorg/jsray-vscode"><code>jsray-vscode</code></a><span class="tag tag--beta">beta</span></li>
         <li>Terminal · <a href="https://github.com/jsrayorg/jsray-terminal"><code>jsray-terminal</code></a><span class="tag tag--beta">beta</span></li>

tools/release.sh

@@ -73,6 +73,23 @@ if [ -n "$(git status --porcelain)" ]; then
   exit 1
 fi
 
+# The release commit's subject is printed beside every file it touched. When it
+# also carries changes a bump did not require, that one sentence becomes the
+# description of files it says nothing about: 0.0.2-beta.3 put "Carry the
+# documentation corrections to npm and the site" on CODE_OF_CONDUCT.md and
+# .github/, neither of which had anything to do with npm or the site.
+#
+# So the last commit may touch only what a bump has to touch. Anything else
+# belongs in its own commit, made before this one — which is also what makes
+# each of those files show a sentence about itself.
+STRAY=$(git show --name-only --format= HEAD | grep -vE '^(package\.json|version\.json|integrity\.json|tokens\.json|vocabulary\.json|CHANGELOG\.md|SECURITY\.md|README\.md|README\.zh-CN\.md|dist/|src/|types/|demo/|docs/versioning(\.zh-CN)?\.md|docs/projects(\.zh-CN)?\.md)' || true)
+if [ -n "$STRAY" ]; then
+  echo "error: the release commit reaches outside a version bump:" >&2
+  printf '  %s\n' $STRAY >&2
+  echo "       split those into their own commits first — see CONTRIBUTING.md." >&2
+  exit 1
+fi
+
 if git rev-parse "$TAG" >/dev/null 2>&1; then
   echo "error: tag $TAG already exists — bump version.json first." >&2
   exit 1