docs: fix bookmark downgrade-guard framing + jj flag in jj guide

6e0795776a6bea04d09255d81453491f29eb3987
humdrum <me@humdrum.me> · 2026-06-19 09:52

parent ad0ec0d8

docs: fix bookmark downgrade-guard framing + jj flag in jj guide

- MIGRATION.md: rewrite downgrade-guard section to accurately state the
  guard is bookmark-scoped with no floor at cutover; attribute the >=
  last-tag constraint to brew upgrade continuity, not the guard
- JUJUTSU.md: update --branch to --bookmark in the "what works
  unchanged" example (flag removed in jj 0.21)
- JUJUTSU.md: add MANUAL.md cross-reference on webhook setup step

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2 files changed

docs/JUJUTSU.md +3 −2

@@ -19,7 +19,7 @@ # clone via jj
 jj git clone soft:<repo>
 
 # push changes
-jj git push --branch main      # or --all
+jj git push --bookmark main    # or --all
 ```
 
 ## Concept mapping
@@ -63,7 +63,8 @@   source: bookmark          # opt in to bookmark-mode releases
   # bookmark_prefix: release/  # default; change only if you need a different prefix
 ```
 
-Register the release webhook (same as tag mode):
+Register the release webhook (same command as tag mode; see [MANUAL.md](MANUAL.md) for webhook
+secret generation and registration details):
 
 ```sh
 ssh soft repo webhook create <name> https://your-host/hooks/release \

docs/MIGRATION.md +11 −4

@@ -146,10 +146,17 @@
 Past tag-based releases already published to the tap are unaffected; users with those versions
 installed can still `brew upgrade` once the first bookmark release lands.
 
-The downgrade guard compares the incoming bookmark version against the highest already-published
-**release bookmark** (not the old tags). This means: after flipping, the **first bookmark release
-must be at or above the highest tag version you already shipped**. If your last tag was `v1.3.0`,
-the first `release/vX.Y.Z` bookmark must be `v1.3.0` or higher or the webhook will reject it.
+The downgrade guard is **bookmark-scoped**: it compares the incoming bookmark version only against
+the highest already-published release bookmark (i.e. other `release/vX.Y.Z` branches). It does not
+consult the old git tags at all. At the moment you flip, there are zero release bookmarks, so the
+guard imposes no floor — it would accept any semver version as the first bookmark release.
+
+The real reason your first bookmark release must be `>=` your last published tag is **Homebrew
+upgrade continuity**: existing tap users have that tag's version installed, and `brew upgrade` only
+moves them forward if the new formula version is strictly higher. That is a convention you must
+honour manually, not something the guard enforces. If your last tag was `v1.3.0`, the first
+`release/vX.Y.Z` bookmark must be `v1.3.0` or higher — otherwise existing users would never
+pick up the new release via `brew upgrade`.
 
 Plan the cutover version accordingly — bumping the patch is fine: `v1.3.1` works.