@autotelic/joggle 0.4.1 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/JOGGLE.md +26 -0
  2. package/package.json +1 -1
package/JOGGLE.md CHANGED
@@ -483,6 +483,32 @@ writes the file as this run alone, which for a scoped run would truncate the
483
483
  ledger. `--allow-unjudged-baseline` is not the shortcut here: it ratifies the
484
484
  thousands nobody looked at, which is a commit nobody can defend.
485
485
 
486
+ ### The cascade, not the conflicts
487
+
488
+ In a deep stack the conflicts are the easy half. Every one of them is a committed
489
+ artifact — a baseline, an answer ledger, a generated catalog — so
490
+ `git rebase -X theirs <parent>` clears the text and the artifacts are rebuilt
491
+ rather than merged.
492
+
493
+ The hard half is ordering. Accepting an identity, or rebuilding a catalog, adds a
494
+ commit to the parent, and that commit re-dirties every child above it: with 21
495
+ children, one fix is 21 re-dirties, and a cascade run between fixes runs once per
496
+ fix. A 22-branch migration spent five cascades that way, not because any rebase
497
+ was hard, but because each pass moved the parent again.
498
+
499
+ So the recipe is three passes, not one per branch:
500
+
501
+ 1. **Finish every accept and every rebuild first**, on every branch. Nothing is
502
+ rebased until the artifacts have stopped moving.
503
+ 2. **Then rebase bottom-up, once**, with `-X theirs` for the artifact conflicts.
504
+ 3. **Then push once**, bottom-up, with `--force-with-lease`.
505
+
506
+ `gh stack rebase` and the stacked-PR bots do exactly these three steps in one pass,
507
+ which is why they exist. An interrupted rebase leaves `rebase-merge/` or
508
+ `index.lock` behind and the next branch fails with "there is already a rebase-merge
509
+ directory": `git rebase --abort` clears it, and a scripted cascade belongs in a
510
+ `trap` that aborts rather than in a run that stops half-rebased.
511
+
486
512
  The baseline is by identity, not by line: rule, kept symbol and cluster
487
513
  membership. Code moves constantly, and a baseline that reports every edit as a
488
514
  new finding is a baseline nobody reads. A rename or a new member does change the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@autotelic/joggle",
3
- "version": "0.4.1",
3
+ "version": "0.4.2",
4
4
  "type": "module",
5
5
  "description": "Cross-file patterns and idioms for TypeScript — the layer above the linter and the typechecker.",
6
6
  "license": "MIT",