pe/josh-sync
2
0
Fork 0
Code Pull Requests Actions Packages Releases Activity

Trim overengineered docs and ADR

Browse Source 
Remove redundant step-by-step subsections from workflow guide (the
table already covers it), tighten ADR-011 alternatives, and remove
version pins that go stale.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
SBPro
2026-03-17 14:55:53 +03:00
parent 4861179c6f
commit 65cc8eaf8a
2 changed files with 5 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/adr/011-linearize-fallback-reverse.md
View File

@@ -15,13 +15,9 @@ This is a legitimate subrepo workflow — teams merge staging branches into main
### Alternatives considered
1. **Fail and log**: The pre-v1.3 behavior. Leaves the sync stuck until someone manually intervenes. Bad for unattended cron-based sync.
2. **Squash all commits into one**: Create a single `commit-tree` with the diff between josh-filtered base and subrepo HEAD. Simple but destroys all commit granularity — 10 unrelated commits appear as one blob on the monorepo PR.
3. **Rewrite subrepo history**: Rebase or filter-branch the subrepo to remove problematic merges. Breaks the sync relationship with the monorepo (josh's SHA mapping becomes invalid) and forces all developers to re-clone.
4. **Linearize: cherry-pick regular commits, squash only merges**: Walk the human commits in order, cherry-pick non-merge commits as-is, and use `cherry-pick -m 1` for merge commits. Preserves individual commit granularity for regular commits; only the problematic merge commits lose their multi-parent structure.
1. **Squash all commits into one**: Simple but destroys all commit granularity.
2. **Rewrite subrepo history**: Breaks josh's SHA mapping, forces all developers to re-clone.
3. **Linearize: cherry-pick regular commits, squash only merges**: Preserves individual commit granularity; only merge commits lose their multi-parent structure.
## Decision
@@ -59,10 +55,4 @@ When the direct push through josh-proxy fails, fall back to option 4: linearize
**Negative:**
- Merge commit semantics are lost on the monorepo side (they appear as regular commits)
- If a merge commit's changes conflict with a prior cherry-picked commit during linearization, the diff-apply fallback may produce a subtly different result than the original merge resolution
- Adds complexity to the reverse sync path (two code paths: direct push and linearize fallback)
**Risk mitigation:**
- The direct push is always tried first — linearization only activates when josh rejects the push
- The monorepo PR is still reviewed by humans before merging
- The original commit SHAs are listed in the PR body for cross-referencing