Skip to content

task: build Shorebird patches from release-specific backport lines #7842

Closed

Description

@NotThatKindOfDrLiz

Description

Replace the current patch-from-main model with a release-specific backport workflow rooted at the immutable Shorebird provenance baseline. Update the executable Codemagic policy, repository workflow rules, patch runbook, and regression tests together.

Context

The current Codemagic workflow accepts patches only from main. At Divine merge velocity, unrelated native, asset, dependency, and Dart work quickly makes that source unsafe or ineligible. Git and Shorebird can still patch the public release from its recorded baseline; our workflow currently prevents that safe path.

This task implements the workflow defined by parent epic #7841. It does not perform the live two-platform operational drill, which is tracked separately.

Implementation notes

  • Define one canonical release-patch branch format that encodes platform and normalized release version.
  • Validate the branch against SHOREBIRD_PLATFORM and RELEASE_VERSION.
  • Continue verifying that the recorded release baseline is an ancestor of HEAD.
  • Keep the conservative native, asset, dependency, Flutter, and Shorebird configuration diff guard.
  • Fixes must land on main first; patch lines receive minimal reviewed backports and are never merged into main.
  • A subsequent patch for the same release must build on the existing patch line so it preserves all fixes in the active patch.
  • Preserve signed releases and patches, immutable private provenance, matching dart-defines, staging publication, explicit stable promotion, and rollback.
  • Extract source validation into a focused testable script if that makes the safety contract clearer than embedded YAML.

Acceptance criteria

  • Codemagic no longer requires the patch source to be main.
  • Codemagic accepts only the canonical release-specific patch branch matching the selected platform and release version.
  • The provenance-recorded release baseline must be an ancestor of the patch source.
  • Current main and a patch branch for another release/platform fail closed.
  • Native, asset, dependency, engine/configuration, and empty-Dart diffs fail closed.
  • The complete baseline-to-patch commit and Dart-file diff is printed for operator review.
  • Existing signing, configuration fingerprint, staging, promotion, and rollback safeguards remain intact.
  • Documentation defines eligibility, branch creation, backport review, cumulative patches, validation, promotion approval, monitoring, rollback, and retirement.
  • AGENTS.md and the canonical workflow rules contain a narrow exception for operational release patch lines.
  • Focused tests cover accepted and rejected source histories and pin the Codemagic contract.
  • All repository checks are green.

Testing

Run the Shorebird provenance/source validator tests, Codemagic configuration tests, project configuration tests, YAML validation, and any focused shell/Ruby/Python tests introduced by the change.

Out of scope

  • Supporting pure-Dart dependency changes; retain the conservative pubspec guard initially.
  • Normal feature delivery through Shorebird.
  • Changing Zapstore or macOS patchability.
  • Executing or promoting a production patch.

Metadata

Metadata

Labels

No labels
No labels

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions