Skip to content

Migrate callers from @main to @v1 tags #1

Description

@taprile314

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:

  • No breaking changes merged to main for at least 4 weeks.
  • All active repos have migrated to the centralized workflows.
  • At least one full release cycle of each type (custom-code preview→stage→production, service production, library release) has run successfully via the reusables.

How

Per docs/contributing.md:

  1. Cut v1.0.0 on main:
    git tag v1.0.0 && git push --tags
  2. Create moving v1 tag:
    git tag -f v1 && git push --tags --force
  3. Update the callers in examples/ to use @v1 instead of @main.
  4. 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

  • v1.0.0 tag exists and v1 moving tag points at it.
  • All examples in this repo reference @v1.
  • All consumer repos reference @v1 (verify with a grep across the org).
  • docs/contributing.md updated to reflect the new steady state (how to cut patch/minor/major after v1).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requesthelp wantedExtra attention is needed

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions