INTER-2266: Improve move tag workflow

.github/workflows/move-v1-tag.yml

@@ -1,32 +1,47 @@
-name: Move v1 Tag
+name: Update Main Version
+run-name: Move ${{ github.event.inputs.major_version }} to ${{ github.event.inputs.target }}
 
 on:
   workflow_dispatch:
+    inputs:
+      target:
+        description: The tag to use
+        required: true
+      major_version:
+        type: choice
+        description: The major version to update
+        required: true
+        default: v1
+        options:
+          - v1
+permissions:
+  contents: write
 
 jobs:
-  move-tag:
+  tag:
     runs-on: ubuntu-latest
-
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v7
-
-      - name: Check branch
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Git config
         run: |
-          if [[ "$GITHUB_REF" != "refs/heads/main" ]]; then
-            echo "This action can only be run on the main branch."
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: Validate target is a tag
+        run: |
+          if ! git show-ref --tags --verify --quiet "refs/tags/${{ github.event.inputs.target }}"; then
+            echo "Error: '${{ github.event.inputs.target }}' is not a valid tag."
             exit 1
           fi
-
-      - name: Set up Git user
+      - name: Validate target tag is reachable from main
         run: |
-          git config user.name "semantic-release-bot"
-          git config user.email "semantic-release-bot@martynus.net"
-
-      - name: Move v1 tag to the latest commit in main
-        run: |
-          git fetch --tags
-          git tag -d v1 || echo "v1 tag not found, continuing"
-          git push origin :refs/tags/v1 || echo "v1 tag not found in origin, continuing"
-          git tag v1
-          git push origin v1
+          commit=$(git rev-list -1 "refs/tags/${{ github.event.inputs.target }}^{}")
+          if ! git merge-base --is-ancestor "$commit" origin/main; then
+            echo "Error: Tag '${{ github.event.inputs.target }}' points to a commit not reachable from main."
+            exit 1
+          fi
+      - name: Tag new target
+        run: git tag -f "${{ github.event.inputs.major_version }}" "${{ github.event.inputs.target }}^{}"
+      - name: Push new tag
+        run: git push origin "${{ github.event.inputs.major_version }}" --force

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) (LTS)
+- [pnpm](https://pnpm.io/) v9
+
+## Setup
+
+```sh
+pnpm install
+```
+
+## Development
+
+### Project structure
+
+This is a **pnpm workspace monorepo** with two types of artifacts:
+
+- **npm packages** in `packages/` - shared configs for ESLint, Prettier, TypeScript, commitlint, and changesets
+- **GitHub Actions** in `.github/actions/` - custom composite and TypeScript actions
+- **Reusable workflows** in `.github/workflows/` - shared CI/CD workflows consumed by other repositories
+
+### Scripts
+
+| Command | Description |
+|---|---|
+| `pnpm run build` | Build all npm packages |
+| `pnpm run build:actions` | Bundle TypeScript GitHub Actions into `dist/` using `@vercel/ncc` |
+| `pnpm run test` | Run tests with Jest |
+| `pnpm run test:coverage` | Run tests with coverage report |
+| `pnpm run lint` | Run ESLint |
+| `pnpm run lint:fix` | Run ESLint with autofix |
+
+### Commit conventions
+
+This repository uses [conventional commits](https://www.conventionalcommits.org/) enforced by commitlint via a husky `commit-msg` hook.
+
+### Building GitHub Actions
+
+If you modify a TypeScript GitHub Action under `.github/actions/`, you **must** run `pnpm run build:actions` and commit the resulting `dist/` files. The `check-dist` CI check will fail if the committed dist is out of sync with the source.
+
+## Releasing
+
+This repository contains two types of publishable artifacts, each with its own release process.
+
+### npm packages
+
+npm packages are released automatically via [changesets](https://github.com/changesets/changesets). To release a new version:
+
+1. Create a changeset in your PR by running `pnpm exec changeset`.
+2. Merge the PR to `main`.
+3. Changesets will open a "Version Packages" PR. Merging that PR publishes the updated packages to npm.
+
+### GitHub Actions and reusable workflows
+
+Actions and reusable workflows are consumed by other repositories via git tags (e.g. `@v1`). To release a new version:
+
+1. Merge your PR with the action/workflow changes to `main`.
+2. Create and push a new semver tag from the merge commit:
+   ```sh
+   git tag v1.x.y
+   git push origin v1.x.y
+   ```
+3. Go to **Actions > Update Main Version** and run the workflow with:
+   - **target**: the tag you just pushed (e.g. `v1.x.y`)
+   - **major_version**: `v1`
+
+   This moves the `v1` tag to point at your new release, so all consumers referencing `@v1` pick up the change.

README.md

@@ -781,3 +781,10 @@ jobs:
 
 Use [`paths-changed`](.github/actions/paths-changed) to keep required checks reporting
 while skipping expensive steps when watched files did not change.
+
+## Releasing
+
+This repository contains two types of publishable artifacts with different release processes. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+- **npm packages** - released automatically via [changesets](https://github.com/changesets/changesets) when PRs with changeset files are merged to `main`.
+- **GitHub Actions and reusable workflows** - released manually by tagging a commit and running the "Update Main Version" workflow to move the `v1` tag.