Improve/automate package.json version bumping on NPM publish & release drafter

[jescalada]

As of #1520, our NPM workflow automatically publishes to NPM whenever we publish a GitHub release. However, it relies on us manually bumping the package.jsons and it doesn't check whether this has been done. If the package.json versions aren't bumped (particularly the main @finos/git-proxy version), this can override existing releases or mess up subsequent release-drafter.yml executions.

Describe the solution you'd like
We should at least check whether a package.json version bump has occurred, and fail the workflow if so.

Ideally, we would have some script that runs automatically to bump the versions appropriately, perhaps during the release-drafter.yml step which computes the next semantic version. This could create a PR that bumps all the relevant package.jsons (currently ./package.json and ./packages/git-proxy-cli/package.json), which we then review/merge to trigger the actual GitHub release, which will in turn create a valid NPM release.

If we go with the auto-bumping script/workflow, we still need to check before running the NPM workflow in case someone forgot to merge the generated bump PR.

Also, the Releases.md doc should be updated to reflect the improved flow.

Additional context
#1516 (comment)
#1516 (comment)
#1520

[kriswest]

There was an action we used to use in the FDC3 repo to check if the version exists on NPM, which effectively accomplished the version bump check, I think the current version just tries to publish and then fails out as that project is similarly manually bumping.

Something like this could work:

name: Check npm version

on:
  release:
    types: [created]  # Trigger when a release is created
  workflow_dispatch:  # Optional manual trigger

jobs:
  check-version:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Get package name and version
        id: pkg
        run: |
          NAME=$(node -p "require('./package.json').name")
          VERSION=$(node -p "require('./package.json').version")
          echo "name=$NAME" >> $GITHUB_OUTPUT
          echo "version=$VERSION" >> $GITHUB_OUTPUT

      - name: Check if version exists on npm
        id: check
        run: |
          PACKAGE=${{ steps.pkg.outputs.name }}
          VERSION=${{ steps.pkg.outputs.version }}

          echo "Checking $PACKAGE@$VERSION on npm..."

          if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
            echo "exists=true" >> $GITHUB_OUTPUT
          else
            echo "exists=false" >> $GITHUB_OUTPUT
          fi

      - name: Fail if version already exists
        if: steps.check.outputs.exists == 'true'
        run: |
          echo "❌ Version already exists on npm. Did you forget to bump it?"
          exit 1

      - name: Success
        if: steps.check.outputs.exists == 'false'
        run: |
          echo "✅ Version does not exist yet. Good to publish."

Or there's a prebuilt action:

- name: Check publish status
  id: check
  uses: tehpsalmist/npm-publish-status-action@v1

- name: Fail if version already exists
  if: ${{ steps.check.outputs.exists == '1' }}
  run: |
    echo "❌ Version already exists on npm"
    exit 1

Finally, conventional commits is designed to help us do this and most users of it automate verison bumps using it:

• if all the commits are chore, docs and fix: bump patch version
• if there are feat commits: bump minor version
• if there are breaking changes (! appended - theres an alternative syntax that means the same): bump major version

Here's a co-pilot's suggestions on actions to handle that:

There are quite a few solid GitHub Actions for auto‑versioning based on Conventional Commits. They fall into three main categories:

• ✅ “Full release automation” (best for most teams)
• ✅ “Version bump only” (lightweight)
• ✅ “PR-based versioning workflows” (more controlled / enterprise-style)

Below is a curated list with when to use each 👇

---

🥇 1. release-please (Google) — best all-round

👉 googleapis/release-please-action

What it does

• Parses Conventional Commits
• Calculates next semver (major/minor/patch)
• Creates a release PR
• Updates package.json + changelog
• Tags + creates GitHub release when merged [github.com]

Why it’s great

• Very widely used (Google-backed)
• Safe model (PR-based instead of auto-push)
• Works well with real production workflows

Example

name: release-please

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          release-type: node
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

✅ Best for:

• Teams that want controlled releases
• Auditability via PRs

---

🥇 2. semantic-release (via GitHub Action)

👉 cycjimmy/semantic-release-action or codfish/semantic-release-action

What it does

• Fully automated
• Reads Conventional Commits
• Determines next version
• Publishes to npm + creates GitHub release [github.com]

Why it’s great

• Industry standard in JS ecosystem
• Zero manual release steps

Example

- uses: actions/checkout@v4

- name: Semantic Release
  uses: cycjimmy/semantic-release-action@v6
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

✅ Best for:

• Fully automated pipelines
• Continuous deployment workflows

⚠️ Trade-off:

• Less human control than release-please

---

🥇 3. changesets/action (monorepos esp.)

👉 changesets/action

What it does

• Creates a PR with version bumps + changelog
• Supports multi-package repos
• Can publish automatically or manually [github.com]

Why it’s great

• The go-to for monorepos
• More explicit control than semantic-release

✅ Best for:

• Monorepos / multi-package repos
• Teams that want structured release batching

---

⚙️ 4. Lightweight “bump-only” actions

a) Conventional commit auto bump

👉 paramsinghvc/gh-action-bump-version

What it does

• Bumps package.json based on commits:
  • feat → minor
  • fix → patch
  • BREAKING CHANGE → major [github.com]
• Tags and pushes back to repo

✅ Best for:

• Simple repos
• Minimal setup

---

b) Version bumper action

👉 tomerfi/version-bumper-action

What it does

• Calculates next version from Conventional Commits
• Outputs version (doesn’t necessarily commit it) [github.com]

✅ Best for:

• Custom pipelines where you control the rest

---

c) Conventional changelog action

👉 TriPSs/conventional-changelog-action

What it does

• Bumps version
• Generates changelog
• Tags release [github.com]

✅ Best for:

• If you want changelog + bump but not full release automation

---

⚡ 5. Hybrid / newer tools

Changesets autopilot (emerging)

• Combines:
  • Conventional commits → auto changesets
  • Version + publish automation [github.com]

✅ Good middle ground between semantic-release and changesets

---

🧠 Which one should YOU pick?

👉 If you want:

“Safe, enterprise-friendly, PR-based releases”

→ ✅ release-please

👉 If you want:

“Fully automated, just push commits and release happens”

→ ✅ semantic-release

👉 If you want:

“Monorepo + multiple packages”

→ ✅ changesets

👉 If you want:

“Simple version bump only”

→ ✅ gh-action-bump-version

---

💡 My practical recommendation

For most teams:

👉 release-please + your npm publish step

Why:

• Prevents accidental releases
• Enforces Conventional Commits
• Clean audit trail
• Works nicely with your earlier “check npm version exists” step