Skip to content

[Stage 0.6] Document contribution, manual synchronization, and release routing #316

Description

@draedful

Parent: #310

Goal

Make branch responsibilities, maintenance scope, manual synchronization, and independent release routing unambiguous.

Scope

  • Document that v1 is stable and maintenance-only, not yet deprecated.
  • Document which pull requests target main and which target v2.
  • Document the v1 change policy: necessary bug fixes, security fixes, and documentation only.
  • Define the manual synchronization task used when main changes.
  • Require each synchronization decision to record:
    • the source main SHA;
    • whether the change applies to v2;
    • the sync PR or an explicit no-port decision;
    • the resulting merge SHA when synchronized.
  • Define that a no-port decision rejects the behavior, while a later full merge may still introduce its ancestry.
  • Require release-candidate and cutover review to neutralize or explicitly resolve any non-applicable content introduced by that full merge.
  • Require synchronization pull requests to use merge commits.
  • State that squash, rebase, and cherry-pick are not the canonical branch sync mechanism.
  • Require drift verification before every v2 release candidate and before cutover.
  • Document the pre-cutover release routes:
    • main / 1.x / latest
    • v2 / 2.x prerelease / next
  • Document the post-cutover release routes:
    • release/v1 / 1.x / v1
    • main / stable 2.x / latest
  • Document formal v1 deprecation as a separate future action.
  • Define issue and pull-request labels or template guidance for v1, v2, synchronization, release, and cutover work.

Acceptance criteria

  • Contributors can determine the correct target branch without maintainer assistance.
  • v1 maintenance scope is explicit.
  • Manual sync triggers, ownership, merge method, SHA tracking, and no-port handling are documented.
  • No scheduled or automatic synchronization is required.
  • Release and preview routing for both lines is documented before and after cutover.
  • Formal v1 deprecation and release-workflow retirement are documented separately.
  • Issue and pull-request routing guidance is available in the repository.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions