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 ### 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. 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.
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. **Linearize: cherry-pick regular commits, squash only merges**: Preserves individual commit granularity; only merge commits lose their multi-parent structure.
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.
## Decision ## Decision
@@ -59,10 +55,4 @@ When the direct push through josh-proxy fails, fall back to option 4: linearize
**Negative:** **Negative:**
- Merge commit semantics are lost on the monorepo side (they appear as regular commits) - 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) - 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

26
docs/guide.md
View File

@@ -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 | | 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) | | 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 ### 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. - **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. 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 ## 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 - 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 - 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. **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.