Once the reusable workflows stabilize (target: ~2–3 months without breaking changes), migrate away from @main references to tagged versions so consumer repos pin to a known-good version.
Why
While everyone is migrating, @main is the right tradeoff: fast iteration, no per-repo PR for every fix. Once things stabilize, the tradeoff flips — a bad commit on main breaks every Refokus repo at once, and there's no escape hatch for a repo to pin to a known-good version.
Moving to tagged versions gives:
- Stability for consumer repos (pinned to
@v1).
- A proper escape hatch: individual repos can stay on
@v1 while new changes ship under @v2 during breaking migrations.
@main still usable for repos that want bleeding edge.
When
Move when these are all true:
How
Per docs/contributing.md:
- Cut
v1.0.0 on main:
git tag v1.0.0 && git push --tags
- Create moving
v1 tag:
git tag -f v1 && git push --tags --force
- Update the callers in
examples/ to use @v1 instead of @main.
- Open a PR in each consumer repo to update the
uses: reference.
Rollout
- Order: same as the initial migration — library → service → custom-code template → custom-code sites.
- Do it over 1–2 weeks, not all at once.
- After all repos are on
@v1, optionally enforce via branch protection rules or a lint rule.
Done when
Once the reusable workflows stabilize (target: ~2–3 months without breaking changes), migrate away from
@mainreferences to tagged versions so consumer repos pin to a known-good version.Why
While everyone is migrating,
@mainis the right tradeoff: fast iteration, no per-repo PR for every fix. Once things stabilize, the tradeoff flips — a bad commit onmainbreaks every Refokus repo at once, and there's no escape hatch for a repo to pin to a known-good version.Moving to tagged versions gives:
@v1).@v1while new changes ship under@v2during breaking migrations.@mainstill usable for repos that want bleeding edge.When
Move when these are all true:
mainfor at least 4 weeks.How
Per docs/contributing.md:
v1.0.0onmain:git tag v1.0.0 && git push --tagsv1tag:git tag -f v1 && git push --tags --forceexamples/to use@v1instead of@main.uses:reference.Rollout
@v1, optionally enforce via branch protection rules or a lint rule.Done when
v1.0.0tag exists andv1moving tag points at it.@v1.@v1(verify with a grep across the org).docs/contributing.mdupdated to reflect the new steady state (how to cut patch/minor/major after v1).