From 92d2600ae7cbba40a8b1c9a99f396af80008dcf8 Mon Sep 17 00:00:00 2001 From: "shoney.arickathil" Date: Sat, 29 Aug 2026 20:48:23 +0200 Subject: [PATCH] docs(commit-history): feature-to-cherry-pick reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - records the workflow: develop on dev, feature prefix as the conventional-commit scope, cherry-pick onto master when ready - prefix registry so two features cannot claim the same prefix; the prefix is claimed before the feature's first commit - cherry-pick log maps dev hashes to the master hashes they produced — they differ, and that mapping is what makes a feature traceable or revertible as a unit after dev moves on - notes the db2-keys seam: written pre-convention on porch-store-middleware, replayed onto dev, replay verified identical - work before 2026-08-29 landed by merge; git log --merges covers it Co-Authored-By: Claude Opus 5 (1M context) (cherry picked from commit 41923eb1f9510ab53804ca8dc6fe30a9a7eac849) --- docs/00-git-commit-history.md | 56 +++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/00-git-commit-history.md diff --git a/docs/00-git-commit-history.md b/docs/00-git-commit-history.md new file mode 100644 index 0000000..706505e --- /dev/null +++ b/docs/00-git-commit-history.md @@ -0,0 +1,56 @@ +# Git commit history — features and their cherry-picks + +Reference for **which commits carried which feature onto `master`**, so a +feature can be traced, re-reviewed, or reverted as a unit long after the +history it was written in has moved on. + +## The workflow this file records + +1. **Development happens on `dev`.** Not on `master`, and not on a fresh + branch per feature. +2. **Every commit on `dev` carries a feature-specific unique prefix**, written + as the conventional-commit scope — `feat(db2-keys): …`, `fix(db2-keys): …`. + The scope, not a bare leading word, so the repo keeps the `feat`/`fix`/`docs` + type it has used throughout. One prefix per feature, reused by every commit + belonging to it, which makes a feature's commits selectable with + `git log --grep` without reading a single diff. +3. **When the feature is ready** — complete, not merely green — `git checkout + master` and **cherry-pick** that feature's commits, in order. +4. **Record the result below**: the `dev` hashes, the `master` hashes the + cherry-pick produced, and the date. The two differ — a cherry-pick makes new + commits — and that mapping is the whole reason this file exists. + +Ready means the same gate as always: no half-implemented feature reaches +master. An annotation the compiler accepts but does not honour counts as +broken, however green the suite. + +## Prefix registry + +One row per feature. The prefix is claimed here before its first commit, so two +features cannot collide. + +| Prefix | Feature | Status | +| --- | --- | --- | +| `commit-history` | this file and the workflow it records | ✅ on `dev` | +| `db2-keys` | databasev2 2 — `resident: keys` storage and readers | on `dev` (`125bd09`, `08abd09`, `0c97fa4`, `f606fc9`). **Not ready**: the loader still refuses the annotation, and updates on such a table are refused rather than implemented | + +## Cherry-picks onto master + +Newest first. `dev` hash is the original; `master` hash is what the cherry-pick +produced. + +| Date | Prefix | Feature | `dev` → `master` | +| --- | --- | --- | --- | +| — | — | *nothing cherry-picked onto master under this convention yet* | — | + +## Before this convention + +Work up to 2026-08-29 landed on `master` by **merging** feature branches, so +those commits keep their original hashes and have no entry here. +`git log --merges master` is the record for that period. + +The `db2-keys` commits are the seam: they were written on +`porch-store-middleware` before this convention (`18ce4d5`, `f9c36ef`, +`11a92df`, `91411ae`) and were replayed onto `dev` with prefixed titles. The +replay was verified identical, not merely applied — `git diff` between the two +branches over `database/`, `runtime/` and `docs/stories/` is empty.