actions/.serena/memories/versioning_system.md

Version System Architecture

Overview

This repository uses a CalVer-based SHA-pinned versioning system for all internal action references.

Version Format

CalVer: vYYYY.MM.DD

• Major: v2025 (year, updated annually)
• Minor: v2025.10 (year.month)
• Patch: v2025.10.18 (year.month.day)

Example: Release v2025.10.18 creates three tags pointing to the same commit:

• v2025.10.18 (patch - specific release)
• v2025.10 (minor - latest October 2025 release)
• v2025 (major - latest 2025 release)

Internal vs External References

Internal (action.yml files)

• Format: ivuorinen/actions/validate-inputs@<40-char-SHA>
• Purpose: Security, reproducibility, precise control
• Example: ivuorinen/actions/validate-inputs@7061aafd35a2f21b57653e34f2b634b2a19334a9

External (user consumption)

• Format: ivuorinen/actions/validate-inputs@v2025
• Purpose: Convenience, always gets latest release
• Options: @v2025, @v2025.10, or @v2025.10.18

Test Workflows

• Format: uses: ./action-name (local reference)
• Location: _tests/integration/workflows/*.yml
• Reason: Tests run within the actions repo context

Internal Workflows

• Format: uses: ./sync-labels (local reference)
• Location: .github/workflows/sync-labels.yml
• Reason: Runs within the actions repo, local is sufficient

Release Process

Creating a Release

# 1. Create release with version tags
make release VERSION=v2025.10.18

# This automatically:
#   - Updates all action.yml SHA refs to current HEAD
#   - Commits the changes
#   - Creates tags: v2025.10.18, v2025.10, v2025
#   - All tags point to the same commit SHA

# 2. Push to remote
git push origin main --tags --force-with-lease

After Each Release

Tags are force-pushed to ensure v2025 and v2025.10 always point to latest:

git push origin v2025 --force
git push origin v2025.10 --force
git push origin v2025.10.18

Or use --tags --force-with-lease to push all at once.

Makefile Targets

make release VERSION=v2025.10.18

Creates new release with version tags and updates all action references.

make update-version-refs MAJOR=v2025

Updates all action.yml files to reference the SHA of the specified major version tag.

make bump-major-version OLD=v2025 NEW=v2026

Annual version bump - replaces all references from one major version to another.

make check-version-refs

Lists all current SHA-pinned references grouped by SHA. Useful for verification.

Helper Scripts (_tools/)

release.sh

Main release script - validates version, updates refs, creates tags.

validate-version.sh

Validates CalVer format (vYYYY.MM.DD, vYYYY.MM, vYYYY).

update-action-refs.sh

Updates all action references to a specific SHA or version tag.

bump-major-version.sh

Handles annual version bumps with commit creation.

check-version-refs.sh

Displays current SHA-pinned references with tag information.

get-action-sha.sh

Retrieves SHA for a specific version tag.

Action Versioning Action

Location: action-versioning/action.yml

Automatically checks if major version tag has moved and updates all action references.

Usage in CI:

- uses: ./action-versioning
  with:
    major-version: v2025

Outputs:

• updated: true/false
• commit-sha: SHA of created commit (if any)
• needs-annual-bump: true/false (year mismatch)

CI Workflow

File: .github/workflows/version-maintenance.yml

Triggers:

• Weekly (Monday 9 AM UTC)
• Manual (workflow_dispatch)

Actions:

1. Checks if v2025 tag has moved
2. Updates action references if needed
3. Creates PR with changes
4. Creates issue if annual bump needed

Annual Version Bump

When: Start of each new year

Process:

# 1. Create new major version tag
git tag -a v2026 -m "Major version v2026"
git push origin v2026

# 2. Bump all references
make bump-major-version OLD=v2025 NEW=v2026

# 3. Update documentation
make docs

# 4. Push changes
git push origin main

Verification

Check Current Refs

make check-version-refs

Verify All Refs Match

All action references should point to the same SHA after a release.

Test External Usage

Create a test repo and use:

uses: ivuorinen/actions/pr-lint@v2025

Migration from @main

All action.yml files have been migrated from:

• uses: ./action-name
• uses: ivuorinen/actions/action-name@main

To:

• uses: ivuorinen/actions/action-name@<SHA>

Test workflows still use ./action-name for local testing.

Security Considerations

SHA Pinning: Prevents supply chain attacks by ensuring exact commit is used.

Version Tags: Provide user-friendly references while maintaining security internally.

Tag Verification: Always verify tags point to expected commits before force-pushing.

Annual Review: Each year requires conscious version bump, preventing accidental drift.