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

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 |
| 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.