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

3.1 KiB

Raw Permalink Blame History

ADR-010: Onboard Workflow with Checkpoint/Resume

Status: Accepted Date: 2026-02

Context

Onboarding an existing subrepo into the monorepo is a multi-step process that involves human interaction (renaming repos, merging PRs). The full flow is:

Prerequisites: rename existing repo, create new empty repo
Import: copy subrepo content into monorepo, create import PR(s)
Wait: human merges the import PR(s)
Reset: force-push josh-filtered history to the new empty repo
(Optional) Migrate open PRs from archived repo

Each step can fail or be interrupted. The process may span hours or days (waiting for PR review). If interrupted, restarting from scratch wastes work and can create duplicate PRs.

Alternatives considered

Single-shot script: Run all steps in sequence. If interrupted, must restart from scratch. Duplicate PRs if import step is re-run.
Manual step-by-step commands: import, then manually run reset. Simple but error-prone — users may forget steps or run them out of order.
Checkpoint/resume with persistent state: Track the current step and intermediate results (PR numbers, reset branches) in persistent state. On re-run, resume from the last completed step.

Decision

Implement josh-sync onboard as a checkpoint/resume workflow with state stored on the josh-sync-state branch at <target>/onboard.json.

State machine

start → importing → waiting-for-merge → resetting → complete

Each transition is persisted before proceeding. Re-running josh-sync onboard <target> reads the current step and resumes.

State schema

{
  "step": "waiting-for-merge",
  "archived_api": "https://host/api/v1/repos/org/repo-archived",
  "archived_url": "git@host:org/repo-archived.git",
  "archived_auth": "ssh",
  "import_prs": { "main": 42 },
  "reset_branches": ["main"],
  "migrated_prs": [
    { "old_number": 5, "new_number": 12, "title": "Fix login" }
  ],
  "timestamp": "2026-02-10T14:30:00Z"
}

Per-branch progress

Import and reset both iterate over branches. Progress is saved after each branch, so interruption mid-iteration resumes at the next unprocessed branch.

PR migration

josh-sync migrate-pr is a separate command that reads onboard state (for the archived repo URL) and tracks migrated PRs. It uses git apply --3way for resilient patch application — the subrepo's content is identical after reset, so patches apply cleanly.

Consequences

Positive:

Safe to interrupt at any point — no duplicate work on resume
Per-branch tracking prevents duplicate import PRs or redundant resets
Archived repo URL stored in state — migrate-pr can operate independently
--restart flag allows starting over if state is corrupted
Human-friendly — prints instructions at each step

Negative:

State management adds complexity (read/write onboard state, step validation)
Interactive steps (read -r) are not suitable for fully automated pipelines
Onboard state persists on the state branch even after completion (minor clutter)
The step machine is linear — cannot skip steps or run them out of order

3.1 KiB Raw Permalink Blame History