Files

Slim B 8ab07b83ab Update docs, changelog, examples, and add ADRs for v1.2

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

2026-02-14 21:28:40 +03:00

1.7 KiB

Raw Blame History

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

Direct push: Fast, but bypasses all review and CI. A bad subrepo commit could break the entire monorepo with no review gate.
Always create a PR: Pushes to a staging branch (auto-sync/subrepo-<branch>-<timestamp>), then creates a PR via API. Humans review and merge.
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

Push subrepo HEAD through josh-proxy to a staging branch: git push -o "base=main" josh://... HEAD:refs/heads/auto-sync/subrepo-main-<ts>
Create PR via Gitea/GitHub API targeting the monorepo's main branch
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)

1.7 KiB Raw Blame History