Skip to content

Versioning policy: patch default, release:minor label, manual major #80

Open
Open
Versioning policy: patch default, release:minor label, manual major#80

Description

@bryanfawcett
Bryan Fawcett (bryanfawcett)
opened on Oct 4, 2026

Owner decision, 2026-10-04: releases were being bumped wrong. Small changes are patch bumps, a minor bump marks a release, and a major bump is only ever made by hand. Each segment holds 999 versions.

The policy

Event Bump Example
A PR merged into staging (the live beta) PATCH 0.27.3 → 0.27.4
staging released to main MINOR 0.27.4 → 0.28.0
A person runs the release workflow with bump: major MAJOR 0.28.0 → 1.0.0
  • Ceiling 999. Patch 999 rolls into the next minor (x.y.999 → x.y+1.0). Minor 999 does not roll into a major: the run fails and asks for a manual major.
  • Manual override. workflow_dispatch takes bump: patch|minor|major. A major is only allowed from a manual run.
  • No labels. The branch decides the bump. There is no release:minor label (none was created).
  • Released versions are not renumbered. The policy applies from the next release.

Shared implementation (nyuchi/.github)

  • .github/actions/next-version: the calculator (next-version.mjs, zero dependencies, with tests) and a composite action. It computes the next version from the highest tag, or checks a version written into the repo.
  • reusable-staging-release.yml: on a push to staging, tag the next patch with GITHUB_TOKEN, so tag-triggered publish workflows do not run for beta builds. It can also make a GitHub pre-release.
  • reusable-auto-tag.yml: before tagging a version read from a file, check it against the policy (main = next minor). With no version-command, it computes the version instead.
  • Docs: AGENTS.md, CONTRIBUTING.md and profile.

Callers pin each workflow and the action to a commit SHA.

Repos

Tracked in the comments below as each PR merges.

Related: the staging branch and live beta subdomain for every repo (separate issue). Once a repo has staging, merges there are patches and only the staging → main release is a minor.

Activity

  1. Bryan Fawcett (bryanfawcett)
    added 3 commits that reference this issue on Oct 4, 2026

    fix(actions): a version that is already tagged needs no policy check

    20af605

    feat(actions): next-version, the org versioning policy in one place (#81

    de909ab

    feat(workflows): staging releases are patches, main releases are mino…

    924e5b4

  2. bryanfawcett commented on Oct 4, 2026

    @bryanfawcett
    Bryan Fawcett (bryanfawcett)
    on Oct 4, 2026
    MemberAuthor

    The shared implementation is merged:

    Adopting it in a repo: add .github/workflows/staging-version.yml. On a push to staging it calls reusable-staging-release.yml@924e5b4, with workflow permissions contents: read and job permissions contents: write. Then point the main release at the next-version action, or at reusable-auto-tag.yml@924e5b4 with a workflow_dispatch bump input. Staging tags are pushed with GITHUB_TOKEN, so push: tags publish workflows do not fire for beta builds.

    The title still says "release:minor label" from the first brief. That approach was replaced: no label exists, and the branch decides the bump. Per-repo PRs follow in the comments below.

  3. Bryan Fawcett (bryanfawcett)
    added 7 commits that reference this issue on Oct 4, 2026

    feat(workflows): reusable-staging-release takes the version to bump f…

    a0d2d79

    docs(changelog): name the PR

    756ebda

    ci: release under the org versioning policy (#17)

    9ce89bb

    ci: release under the org versioning policy

    cda0d79

    ci: release under the org versioning policy (#91)

    9a92961

    ci: release under the org versioning policy (#15)

    74d0af7

    ci: release under the org versioning policy (#23)

    e4dfda5

  4. bryanfawcett commented on Oct 4, 2026

    @bryanfawcett
    Bryan Fawcett (bryanfawcett)
    on Oct 4, 2026
    MemberAuthor

    Callers of reusable-auto-tag. All are now pinned to 924e5b4, take a workflow_dispatch bump input (a major only by hand), and have staging-version.yml, which does nothing until a staging branch exists. Each also has docs and, where the repo keeps a changelog, a CHANGELOG note. All seven PRs merged with green checks.

    Repo PR Post-merge auto-tag
    bundu-labs/marketing #128 ✅ no-op (v4.0.100 already tagged)
    mukoko-dev/mukoko-events-mcp #25 ❌ 403 on tag push. This was already failing in the 4 runs before this PR: RELEASE_BUMP_TOKEN cannot push to this repo. The policy check passed (2.1.0-beta.1, first release, tag mcp-v2.1.0-beta.1). Owner: grant the PAT access to this repo, then re-run.
    nyuchi/auto-seo-manager #17 ✅ no-op
    nyuchi/mcp-ynab #37 ✅ no-op
    nyuchi/nyuchi-docs #91 ✅ no-op
    nyuchi/nyuchi-travel-addons #15 ✅ no-op
    siafuDB/siafudb #23 ✅ no-op

    None of these has a staging branch yet. Until one exists, every release to main must be a minor, so each one uses up a minor version. All seven are candidates for the staging-branch rollout.

  5. Bryan Fawcett (bryanfawcett)
    added 3 commits that reference this issue on Oct 4, 2026

    ci(release): follow the org versioning policy (#242)

    0f243cc

    ci(release): follow the org versioning policy (#67)

    f0af5fb

    ci(auto-tag): follow the org versioning policy (#71)

    d484b34

  6. 68 remaining items

  7. Bryan Fawcett (bryanfawcett)
    added 7 commits that reference this issue on Oct 5, 2026

    ci: tag merges into staging and run CI on staging (#14) (#15)

    febcf66

    ci: tag each release to main as the next minor (#57)

    8b2c0a9

    chore(release): v4.5.0 (#453)

    a30f977

    release: host-derived MCP resource URL, staging beta, .DS_Store (#28)

    30dbdb3

    ci: tag staging merges as patches; Worker beta from staging as a prev…

    902199a

    ci: tag staging merges as patches; Worker beta from staging as a prev…

    c63d71c

    docs: keep main's versioning-policy text on staging (#76)

    1787535

  8. bryanfawcett commented on Oct 6, 2026

    @bryanfawcett
    Bryan Fawcett (bryanfawcett)
    on Oct 6, 2026
    MemberAuthor

    Follow-up from the 2026-10-06 staging-to-main releases (code review on the release PRs): reusable-staging-release.yml tags whatever commit started the run and never checks the branch. Every caller's staging-version.yml keeps workflow_dispatch, and once the file is on main (already the case in auto-seo-manager, data-infra, nyuchi-docs, web-services and others) the Actions "Run workflow" form defaults to main. A manual run without switching branch would put a beta patch tag and a "(beta)" pre-release on a main commit and move the shared version sequence on.

    Recommendation: guard it once, upstream — in the reusable workflow, refuse (or no-op) when github.ref != 'refs/heads/staging' unless ref: is passed explicitly — then bump the pinned SHA in callers. That fixes every repo at once instead of diverging the caller template per repo. Manual-only, so not urgent.

    🤖 Generated with Claude Code

  9. Bryan Fawcett (bryanfawcett)
    added 7 commits that reference this issue on Oct 6, 2026

    chore: version 1.9.0 for the release to main (#17)

    6519622

    chore: version 1.8.0 for the release to main (#19)

    16afdba

    fix(workflows): reusable-staging-release refuses to tag anything but …

    2e18b3f

    chore: version 0.2.0 for the release to main (#94)

    4934bf5

    feat(workflows): release-version-check, the enterprise required versi…

    93d089f

    release: release-version-check and staging tagging (#92)

    914c4da

    chore(rust): Mzizi Roots crates 0.2.0 (#463)

    7e666cd
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