Slim B
8ab07b83ab
- Add v1.1.0 and v1.2.0 changelog entries - Add exclude field to config reference and example config - Add ADRs documenting all major design decisions - Fix step numbering in reverse_sync() - Fix action.yml to copy VERSION file - Add dist/ and .env to .gitignore - Use refs/tags/ format for Nix flake tag refs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
42 lines
1.7 KiB
Markdown
42 lines
1.7 KiB
Markdown
# ADR-004: Always-PR Policy for Reverse Sync
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-01
|
|
|
|
## Context
|
|
|
|
Reverse sync brings subrepo changes back into the monorepo. The monorepo is the source of truth and typically has CI checks, code review requirements, and branch protection rules. Pushing directly to the monorepo's main branch would bypass these safeguards.
|
|
|
|
### Alternatives considered
|
|
|
|
1. **Direct push**: Fast, but bypasses all review and CI. A bad subrepo commit could break the entire monorepo with no review gate.
|
|
|
|
2. **Always create a PR**: Pushes to a staging branch (`auto-sync/subrepo-<branch>-<timestamp>`), then creates a PR via API. Humans review and merge.
|
|
|
|
3. **Configurable per-target**: Let users choose direct push vs PR. Adds complexity and a dangerous default.
|
|
|
|
## Decision
|
|
|
|
Reverse sync always creates a PR on the monorepo. Never pushes directly to the target branch.
|
|
|
|
### Implementation
|
|
|
|
1. Push subrepo HEAD through josh-proxy to a staging branch: `git push -o "base=main" josh://... HEAD:refs/heads/auto-sync/subrepo-main-<ts>`
|
|
2. Create PR via Gitea/GitHub API targeting the monorepo's main branch
|
|
3. PR includes a review checklist: scoped to subfolder, no leaked credentials, CI passes
|
|
|
|
The `-o "base=main"` option tells josh-proxy which monorepo branch to map the push against.
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
- All monorepo changes go through review — consistent with team workflow
|
|
- CI runs on the PR branch before merge
|
|
- Bad subrepo changes are caught before they affect the monorepo
|
|
- Audit trail via PR history
|
|
|
|
**Negative:**
|
|
- Reverse sync is not instant — requires human action to merge the PR
|
|
- Stale PRs accumulate if subrepo changes frequently but PRs aren't merged promptly
|
|
- Adds API dependency (needs token with PR creation scope)
|