From 65cc8eaf8ac71cfcabc5b677f41b8ccea0012f3c Mon Sep 17 00:00:00 2001 From: SBPro Date: Tue, 17 Mar 2026 14:55:53 +0300 Subject: [PATCH] Trim overengineered docs and ADR 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) --- docs/adr/011-linearize-fallback-reverse.md | 16 +++---------- docs/guide.md | 26 ++-------------------- 2 files changed, 5 insertions(+), 37 deletions(-) diff --git a/docs/adr/011-linearize-fallback-reverse.md b/docs/adr/011-linearize-fallback-reverse.md index 80e3261..1974498 100644 --- a/docs/adr/011-linearize-fallback-reverse.md +++ b/docs/adr/011-linearize-fallback-reverse.md @@ -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 diff --git a/docs/guide.md b/docs/guide.md index 38f4a67..fe883c9 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -538,28 +538,6 @@ This means cross-branch merges (e.g., `stage` → `main`) must happen on the mon | Hotfix to `main` | **Either side** | Single commit or small PR — works everywhere | | Config/CI changes (monorepo-only) | **Monorepo** | Not synced to subrepo (use `exclude` for monorepo-only files) | -### Feature development (subrepo) - -This is the primary workflow for subrepo developers: - -1. Create a feature branch from `main` (or whichever synced branch) -2. Develop, commit, push -3. Open a PR targeting `main` on the subrepo -4. Merge the PR (merge commit, squash, or rebase — all work) -5. Reverse sync picks up the new commits and creates a PR on the monorepo - -Any merge strategy works because the feature branch lineage stays within josh's mapped history. - -### Cross-branch merges (monorepo) - -When promoting `stage` to `main`, or catching up `stage` with `main`: - -1. Open a PR on the **monorepo** merging `stage` → `main` (or `main` → `stage`) -2. Review and merge on the monorepo -3. Forward sync propagates the result to the subrepo's `main` and `stage` branches - -This works because josh does the filtering — it computes the subrepo view from the monorepo merge result, rather than trying to reconstruct a monorepo merge from subrepo commits. - ### What to avoid - **Don't merge `stage` into `main` on the subrepo with a merge commit.** The merge parents include commits created on the subrepo side (forward sync merges, criss-cross merges) that josh has no mapping for. Josh rejects the push with a 500 error. @@ -570,7 +548,7 @@ This works because josh does the filtering — it computes the subrepo view from Use a **squash merge**. A squash merge produces a single commit with one parent — josh can always map it. You lose the individual commit history on the target branch, but the sync goes through cleanly. -As a safety net, josh-sync v1.3+ automatically falls back to linearizing the history when josh rejects a push — cherry-picking regular commits individually and squashing only the problematic merge commits. See the [troubleshooting section](#josh-rejected-push-reverse-sync) and [ADR-011](adr/011-linearize-fallback-reverse.md). +As a safety net, josh-sync automatically falls back to linearizing the history when josh rejects a push — cherry-picking regular commits individually and squashing only the problematic merge commits. See the [troubleshooting section](#josh-rejected-push-reverse-sync) and [ADR-011](adr/011-linearize-fallback-reverse.md). ## Excluding Files from Sync @@ -688,7 +666,7 @@ rejecting merge with 2 parents: - That branch contains auto-sync merge commits or other history that doesn't exist in josh's filtered view - Someone merges `main` into a feature/staging branch and then merges it back — the criss-cross parents confuse josh's mapping -**Automatic handling (v1.3+):** josh-sync automatically falls back to linearizing the history when the direct push fails. Regular commits are cherry-picked individually (preserving authorship and messages), while merge commits are squashed into single commits via `cherry-pick -m 1`. The PR notes when this fallback was used. See [ADR-011](adr/011-linearize-fallback-reverse.md). +**Automatic handling:** josh-sync automatically falls back to linearizing the history when the direct push fails. Regular commits are cherry-picked individually (preserving authorship and messages), while merge commits are squashed into single commits via `cherry-pick -m 1`. The PR notes when this fallback was used. See [ADR-011](adr/011-linearize-fallback-reverse.md). **Prevention:** In josh-synced subrepos, prefer **squash merges** when merging long-lived branches (stage, develop) into the synced branch. Squash merges produce a single commit with no merge parents, which josh can always map. Regular feature branch merges (short-lived, no auto-sync history) are usually fine.