Release Pipeline: migrate from version-specific branches to main/development

[jeanmachuca]

Release Pipeline: migrate from version-specific branches to main/development

Repo: QuickCorp/qcobjects-new-app

Current state

The repo has version-specific branches (v2.4, v2.4-ts, v2.5-beta) and three separate npm publish workflows (npmpublish-beta.yml, npmpublish-lts.yml, npmpublish-main.yml).

Why this change

Version-specific branches add complexity: CI workflows need per-branch configuration, PR paths are unclear, and promoting a beta to LTS requires manual cross-branch coordination. A single development branch with tag-based release channels simplifies everything.

What changed

• Removed all version-specific branches (v2.4, v2.4-ts, v2.5-beta)
• Single active development branch: development
• Release channel is encoded in the tag suffix, not in a branch name
• Old version tracks preserved as archive tags

Branch model

main          ← release digest (merged from development via PR)
development   ← single active development branch
feature/*     ← topic branches, PR into development
fix/*
bugfix/*

Release channels (tags)

Tag pattern	npm dist-tag	Triggered by
vX.Y.Z	latest	consolidated npmpublish.yml
vX.Y.Z-lts	lts	consolidated npmpublish.yml
vX.Y.Z-beta	beta	consolidated npmpublish.yml

Promotion workflow

1. Daily work on development branch
2. v-patch --git --npm → tag vX.Y.Z-beta (beta publish)
3. Change VERSION suffix → v-patch --git --npm → tag vX.Y.Z-lts (LTS publish)
4. PR development → main → merge → tag vX.Y.Z on main (latest publish)

Branch snapshot and removal steps

git fetch --all --prune
git tag archive/v2.4 origin/v2.4
git push origin archive/v2.4
git tag archive/v2.4-ts origin/v2.4-ts
git push origin archive/v2.4-ts
git checkout -b development origin/v2.5-beta
git push -u origin development
git push origin --delete v2.5-beta v2.4 v2.4-ts
git branch -d v2.5-beta

CI pipeline updates

File	Change
npmpublish-beta.yml	Remove — consolidated into single npmpublish.yml
npmpublish-lts.yml	Remove — consolidated into single npmpublish.yml
npmpublish-main.yml	Replace with consolidated npmpublish.yml using tag-suffix detection
codeql-analysis.yml	Branch targets to [main, development]

Consolidated workflow pattern:

on:
  push:
    tags: ['v*']
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - name: Set npm dist-tag
        run: |
          VER="${GITHUB_REF_NAME#v}"
          case "$VER" in
            *-lts)  TAG=lts ;;
            *-beta) TAG=beta ;;
            *)      TAG=latest ;;
          esac
          npm dist-tag add "$(node -p "require('./package.json').name")@${VER}" "$TAG"

Archived tracks

Archive tag	Source branch
archive/v2.4	origin/v2.4
archive/v2.4-ts	origin/v2.4-ts

Future considerations

• When starting a new architecture wave, branch from main into a feature branch, develop on development, and release via the same tag flow
• Archived branches are always accessible via the archive tags