Skip to main content

Versioning

Consistent versioning enables reliable deployments and rollbacks. This guide covers semantic versioning, automatic and manual version bumps, and creating GitHub releases.

What You'll Learn​

  • Semantic versioning strategy for the platform
  • Automatic patch versions on merge
  • Manual minor/major releases with cut-tag workflows
  • Creating GitHub releases with artifacts

Semantic Versioning​

The platform uses Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH
  │     │     └── Bug fixes, no API changes
  │     └──────── New features, backwards compatible
  └────────────── Breaking changes

Examples:

  • 1.0.0 → 1.0.1: Bug fix
  • 1.0.1 → 1.1.0: New feature added
  • 1.1.0 → 2.0.0: Breaking API change

Version Bump Strategy​

The platform uses a two-tier approach to version management:

TriggerVersion BumpAutomation
Merge to mainPatch (x.y.Z)Automatic
Manual releaseMinor (x.Y.0) or Major (X.0.0)Manual workflow dispatch

Automatic Patch Versions​

Every merge to main automatically creates a patch release. This ensures:

  • Every main branch commit has a version
  • Continuous delivery to dev environment
  • Traceable deployments
# In build.yml - runs after successful build on main
cut-patch:
  needs: build
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: p6m-actions/python-uv-cut-tag@v1
      with:
        bump: patch

Manual Minor/Major Versions​

For significant releases, use the cut-tag workflow with manual dispatch:

# cut-tag.yml
name: Cut Tag

on:
  workflow_dispatch:
    inputs:
      bump:
        description: 'Version bump type'
        required: true
        type: choice
        options:
          - patch
          - minor
          - major

Cut-Tag Actions​

Each language has a dedicated cut-tag action that understands its version file format:

LanguageActionVersion File
Python (uv)python-uv-cut-tagpyproject.toml
.NETdotnet-cut-tag*.csproj
Javajava-maven-cut-tagpom.xml
Rustrust-cut-tagCargo.toml
JavaScriptjs-pnpm-cut-tagpackage.json

How Cut-Tag Works​

  1. Read current version from language-specific file
  2. Calculate new version based on bump type
  3. Update version file with new version
  4. Commit the change to the repository
  5. Create Git tag (e.g., v1.2.3)

The Git tag created here is used later by the Promotion workflow to identify which release to deploy to staging and production.

Common Inputs​

InputDescriptionDefault
bumpVersion component to bump: patch, minor, majorpatch
prereleasePrerelease identifier (e.g., alpha, beta, rc)—
pushWhether to push the tagtrue

Outputs​

OutputDescription
versionThe new version number (e.g., 1.2.3)
tagThe Git tag created (e.g., v1.2.3)
previous-versionThe version before bumping

Complete Cut-Tag Workflow​

jobs:
  cut-tag:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.tag.outputs.version }}
      tag: ${{ steps.tag.outputs.tag }}
    steps:
      - uses: actions/checkout@v4

      - name: Cut tag
        id: tag
        uses: p6m-actions/python-uv-cut-tag@v1
        with:
          bump: ${{ inputs.bump }}

      - name: Build and publish
        # Build with new version...

      - name: Create GitHub release
        uses: p6m-actions/repository-release@v1
        with:
          tag: ${{ steps.tag.outputs.tag }}
          name: ${{ steps.tag.outputs.version }}

GitHub Releases​

After cutting a tag, create a GitHub release to record the version with artifacts and release notes. See GitHub Releases for details on:

  • Creating releases with the repository-release action
  • Configuring automatic release notes
  • Handling prerelease versions (alpha, beta, rc)

Version Flow Example​

main branch: v1.0.0
     │
     ├── PR merged → v1.0.1 (auto patch)
     │
     ├── PR merged → v1.0.2 (auto patch)
     │
     ├── Manual "minor" release → v1.1.0
     │
     ├── PR merged → v1.1.1 (auto patch)
     │
     └── Manual "major" release → v2.0.0

Best Practices​

Commit Messages​

Use conventional commit messages for better release notes:

feat: add user authentication endpoint
fix: resolve timeout in batch processing
docs: update API reference
chore: upgrade dependencies

Branch Protection​

Configure branch protection rules on main:

  • Require pull request reviews
  • Require status checks to pass
  • Require branches to be up to date

This ensures all changes go through CI before versioning.

Tag Naming​

The cut-tag actions create tags with v prefix by default:

  • Tag: v1.2.3
  • Version: 1.2.3

This convention distinguishes version tags from other tags.