diff --git a/src/docs/README.md b/src/docs/README.md index 33f613774..5487f6ec0 100644 --- a/src/docs/README.md +++ b/src/docs/README.md @@ -16,6 +16,7 @@ Start with [Architecture](architecture.md) for the system overview, then use the - [Changelog](https://github.com/hivecommons/hive/blob/v4/CHANGELOG.md) — recent user-visible changes and release notes. - [Release channels](release-channels.md) — `stable`/`candidate`/`edge` moving image tags, switching a hive to a channel, and the `stable (v4)` version pill. - [v4 stable soak and promotion policy](stable-soak-policy.md) — the proposed gate between `candidate` and `stable`: soak conditions, immutable short-SHA rollback tags, and the emergency exception path. Until the CI promotion step lands, `stable` is a compatibility tag, not evidence of longer soak. +- [v4 → v5 forward-port sync policy](v5-sync-policy.md) — proposed cadence, ownership, merge-commit top-up procedure, and the PR/review contract for keeping `v5` topped up with `v4`; protects the v5 GA bar from unbounded drift. - [HiveCommons migration tracker](hivecommons-migration.md) — phased org/package migration status, operator promises, and communications checklist. - [dibs domain cutover](dibs-domain-cutover.md) — staged operator sequence for moving dibs to `dibs.hivecommons.dev`, including DNS, Let's Encrypt quota hold, Certificate/Ingress manifests, redirect verification, and rollback. - [Serving spokes from the fleet wildcard certificate](spoke-wildcard-tls.md) — how to point a cluster's provisioned spokes at the wildcard instead of one certificate per hive, the two cluster prerequisites that must hold first, and which hosts a wildcard cannot cover. diff --git a/src/docs/v5-sync-policy.md b/src/docs/v5-sync-policy.md new file mode 100644 index 000000000..7f361a61a --- /dev/null +++ b/src/docs/v5-sync-policy.md @@ -0,0 +1,138 @@ +# v4 → v5 forward-port sync policy + +> **Status: active.** This page documents the v4→v5 sync practice used by +> [#5845](https://github.com/hivecommons/hive/pull/5845), +> [#6046](https://github.com/hivecommons/hive/pull/6046), and +> [#6053](https://github.com/hivecommons/hive/pull/6053). Tracking issue: +> [#6051](https://github.com/hivecommons/hive/issues/6051). + +Hive develops on two lines ([ROADMAP.md](../../ROADMAP.md)): `v4` is the +supported stable default branch, and `v5` is the RFC-gated next generation. +Most day-to-day work targets `v4` ([CONTRIBUTING.md](../../CONTRIBUTING.md)), +so `v5` must be topped up by **forward-port sync PRs**. Historically these +have been ad hoc: #4058, #4087, #4313, #5017 (436 commits), #5472, #5845, +#6046, and #6053. This page makes the trigger, owner, procedure, and review +expectations explicit because the [v5 GA bar](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-ga.md) +requires green `v5` gates over a soak window and a v4→v5 migration guide — +both of which degrade as drift grows. + +## Why drift is a GA risk, not housekeeping + +- **Sync size grows superlinearly.** The longer the gap, the more v4 changes + land in files v5 has split or refactored, turning a mechanical merge into + manual re-application of intent. +- **Review quality collapses with size.** A very large sync PR cannot be + reviewed line-by-line; without a stated review contract it is merged on + trust. +- **The GA soak clock resets.** "Required `v5` build/test gates are green for + the agreed soak window" cannot be satisfied while v5 alternates between + stale and mid-merge. + +## Sync trigger (cadence) + +Open a sync PR when **either** condition holds, whichever comes first: + +1. A **v4 release tag** is cut (for example `v4.17.1`), or +2. One week has passed since the previous completed sync. + +Small, frequent syncs are the point: they keep each PR reviewable and keep +v5's CI signal meaningful. The drift counter should usually return to zero; if +it does not, the remaining commits must be named as intentional v5-only +skips/divergences in the PR body. + +## Ownership + +- Syncs are owned by the maintainer group. Each sync PR still has a **single + named driver** — the person or automation account that opens it — responsible + for getting it green and merged. +- Hive's `ci-maintainer` agent may open or refresh the sync PR, but maintainers + own review, conflict decisions, approvals, and merge readiness. +- A sync PR that goes red and idle for more than a few days should be treated + as an incident against the GA bar, not background noise: fix it, or close and + restart from the current tips. + +## Procedure (merge-commit top-up) + +The established style is a **merge commit**, not a cherry-pick series: + +1. Branch from the current `v5` tip, then merge the current `v4` tip. +2. Resolve conflicts by **preserving v5's layout** and re-applying v4 intent in + the files' new homes. Where a v4 change has no v5 counterpart because the + subsystem was removed or deliberately replaced, skip it and say why in the + PR body. +3. Keep v5's own policy where the release lines intentionally differ: version + strings, release tags, image channels, branch names, and v5-only docs remain + v5-shaped even when the v4 change touched adjacent code. +4. Ensure the merge brings v5 up to the **current `origin/v4` tip** unless the + PR body explicitly lists intentional skips. Do not stop merely because drift + is below a threshold. +5. Sign off the merge commit (`git commit -s`). The DCO check runs on sync + merges like any other PR. +6. Run the v5 verification checklist before opening the PR or before marking it + ready for review. + +## Verification checklist + +Before merge, a sync PR must have: + +- `go test -race ./pkg/... ./cmd/...` passing from `src/` on the v5 branch. +- The kick-governor tests passing. If they are included in the package command + above, record that; otherwise run their explicit package/test selector and + record it in the PR body. +- The docs link check passing: `python3 src/scripts/check-docs-links.py`. +- Required GitHub checks green (Playwright/skipped lanes are not blockers when + they are not required for the sync). +- DCO present on the merge commit. + +## Confirming zero delta + +After fetching both branches, this command reports how many v4 commits are not +reachable from v5: + +```sh +git rev-list --count origin/v5..origin/v4 +``` + +A clean sync reports `0`. A non-zero result is allowed only when every remaining +commit is listed in the PR body as an intentional v5 divergence or skip. + +## PR body contract + +Every sync PR body must include: + +- The **v4 range** covered, including the final v4 tip SHA. +- A **ported-changes list**: each v4 PR in the range, either ported (with a + note when it landed in a relocated file) or explicitly skipped with reason. +- Any **intentional divergences** introduced during conflict resolution, + especially v5-only version/tag/image-channel policy. +- The verification commands and results from the checklist above. +- The zero-delta result, or the named/skipped commits that explain a non-zero + result. + +## Review contract + +Reviewers of a sync PR are **not** expected to re-review v4 content that +already passed v4 review. They are expected to verify: + +1. The ported-changes list is complete against + `git log --oneline origin/v5..origin/v4` for the stated range. +2. Conflict resolutions in split/refactored files preserve v4 intent while + keeping v5's layout and release-line policy. +3. Explicitly skipped changes have a stated reason. +4. The verification checklist is green and the DCO sign-off is present. + +This narrower contract is what makes a large-but-honest sync mergeable without +pretending it received line-by-line review. + +## Relationship to other documents + +- [ROADMAP.md](../../ROADMAP.md) — release-line trajectory; the v4→v5 + migration path is part of the v5 GA bar. +- [`src/docs/v5-ga.md` (v5 branch)](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-ga.md) + — the GA checklist this policy protects; tracker + [#6016](https://github.com/hivecommons/hive/issues/6016). +- [Release channels](release-channels.md) — `v5` publishes `edge`; a stale or + red v5 makes `edge` misleading. +- [CONTRIBUTING.md](../../CONTRIBUTING.md) — contributor-facing branch + guidance (target `v4`); this page is the maintainer-facing counterpart for + how that work reaches `v5`.