Skip to main content

README

GitLab Versioning and Release Management

Overview

This directory contains comprehensive documentation for versioning, release automation, and changelog generation in the Agent Platform. We follow Semantic Versioning with automated version bumping through Conventional Commits and a release branch model.

Quick Links

Agent Platform Versioning Strategy

Current Approach

Platform Version: v0.3.x
 Release Branch: release/v0.3.x
 Auto-patch: v0.3.0  v0.3.1  v0.3.2  ...
 Core Projects: Synchronized (all v0.3.x)
 Agent Projects: Independent versions

Key Principles

  1. Semantic Versioning - Follow SemVer 2.0.0 strictly
  2. Conventional Commits - Automate version bumping from commit messages
  3. Release Branches - Long-lived release/vX.Y.x branches for each minor version
  4. Auto-patching - CI/CD automatically increments patch version on merge
  5. Group Milestones - Coordinate work across projects
  6. Automated Everything - Versions, changelogs, releases all automated

Workflow Summary

For Developers

# 1. Create issue with milestone
glab issue create --milestone v0.3.x --title "Add OAuth2 support"

# 2. GitLab creates branch: 106-add-oauth2-support

# 3. Work in worktree
cd .worktrees/2026-01-08/openstandardagents/106-add-oauth2-support/

# 4. Commit with conventional format
git commit -m "feat(auth): add OAuth2 authentication"

# 5. Push and create MR
git push origin 106-add-oauth2-support
glab mr create --target-branch release/v0.3.x --milestone v0.3.x

# 6. On merge: CI automatically creates v0.3.5

For Release Managers

# 1. Monitor milestone progress
glab api "/groups/blueflyio%2Fagent-platform/milestones?title=v0.3.x"

# 2. Review pending releases
glab mr list --milestone v0.3.x --state merged

# 3. Trigger release (manual approval in CI)
# CI calculates version, generates changelog, creates release

# 4. Verify release
glab release view v0.3.5

# 5. Close milestone when series complete
glab milestone close v0.3.x

Documentation Guide

Getting Started

  1. New to versioning? Start with Semantic Versioning Guide
  2. Setting up automation? Read Automated Version Bumping
  3. Understanding our workflow? See Release Branch Strategy

Deep Dives

Quick Reference

Version Format

vMAJOR.MINOR.PATCH

v0.3.5
  
   Auto-incremented by CI on each merge
  Determined by release branch (release/v0.3.x)
 Determined by release branch

Commit Types

TypeDescriptionExample
featNew featurefeat(auth): add OAuth2
fixBug fixfix(api): resolve memory leak
docsDocumentationdocs: update API guide
refactorCode refactoringrefactor: simplify auth logic
perfPerformanceperf: optimize queries
testTeststest: add integration tests
choreMaintenancechore: update dependencies

Branch Structure

main
  
release/v0.3.x  v0.3.0, v0.3.1, v0.3.2, ...
  
106-issue-slug (feature branches)

Common Tasks

Creating a New Release Branch

# From main
git checkout main
git pull origin main

# Create release branch
git checkout -b release/v0.4.x
git push origin release/v0.4.x

# Create group milestone
glab milestone create v0.4.x \
  --group blueflyio/agent-platform \
  --title "v0.4.x Release Series"

Triggering a Release

# Merge MR to release branch
# CI pipeline runs automatically

# Stage: calculate-version
# - Determines next patch version

# Stage: build-artifacts
# - Builds binaries and packages

# Stage: generate-release-notes
# - Creates changelog from commits

# Stage: create-gitlab-release (manual trigger)
# - Creates git tag
# - Creates GitLab release
# - Uploads assets
# - Collects evidence

Hotfixing an Old Version

# 1. Create fix on latest release branch first (upstream-first)
git checkout release/v0.3.x
git pull origin release/v0.3.x

# 2. Create hotfix branch
git checkout -b hotfix/150-critical-fix

# 3. Develop fix
git commit -m "fix: resolve critical security issue"
git push origin hotfix/150-critical-fix

# 4. Create MR targeting release/v0.3.x
glab mr create --target-branch release/v0.3.x

# 5. After merge: CI creates v0.3.6

# 6. If needed, backport to older release branch
git checkout release/v0.2.x
git cherry-pick <commit-hash>
git push origin release/v0.2.x
# CI creates v0.2.7

Checking Version Synchronization

# Core projects should be synchronized
./scripts/check-core-sync.sh v0.3.5

# Output:
#  agent-core: v0.3.5
#  agent-sdk: v0.3.5
#  agent-cli: v0.3.5
#  agent-registry: v0.3.5
#  agent-gateway: v0.3.5

Tools and Configuration

Required Tools

  • Node.js - Runtime for automation tools
  • semantic-release - Version bumping and release automation
  • commitlint - Validate conventional commits
  • glab - GitLab CLI for API operations
  • git - Version control

Installation

# Install semantic-release and plugins
npm install --save-dev \
  semantic-release \
  @semantic-release/git \
  @semantic-release/gitlab \
  @semantic-release/changelog \
  @semantic-release/commit-analyzer \
  @semantic-release/release-notes-generator

# Install commitlint
npm install --save-dev \
  @commitlint/cli \
  @commitlint/config-conventional

# Install husky for git hooks
npm install --save-dev husky
npx husky init

Configuration Files

[object Object] - Semantic Release

{
  "branches": [
    "main",
    {
      "name": "release/v+([0-9])?(.{+([0-9]),x}).x",
      "prerelease": false
    }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/gitlab",
    "@semantic-release/git"
  ]
}

[object Object] - Commitlint

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'chore', 'ci', 'revert'
    ]]
  }
};

[object Object] - Git Hook

#!/bin/sh
npx --no-install commitlint --edit $1

CI/CD Pipeline

Pipeline Stages

stages:
  - validate    # Validate commits and version format
  - test        # Run tests
  - build       # Build artifacts
  - version     # Calculate next version
  - release     # Create release (manual trigger)
  - publish     # Publish to registries

Key Jobs

  1. validate-commits - Ensure conventional commit format
  2. calculate-version - Determine next patch version
  3. build-artifacts - Create distribution packages
  4. generate-release-notes - Create changelog
  5. create-gitlab-release - Tag and release (manual)

Best Practices

DO

  • Follow Semantic Versioning strictly
  • Use Conventional Commits consistently
  • Let CI/CD handle versioning automatically
  • Document breaking changes clearly
  • Link commits to issues
  • Test before releasing
  • Review generated release notes
  • Coordinate core project releases
  • Maintain compatibility matrix

DON'T

  • Manually edit version numbers
  • Skip commit message validation
  • Create arbitrary git tags
  • Modify released versions
  • Rush releases without testing
  • Forget to update documentation
  • Mix manual and automated processes
  • Break backward compatibility in patches

Troubleshooting

Common Issues

Invalid Commit Messages

Problem: CI fails with "invalid commit format"

Solution: Follow conventional commits:

# Bad
git commit -m "fixed bug"

# Good
git commit -m "fix(api): resolve null pointer exception"

Version Already Exists

Problem: Tag v0.3.5 already exists

Solution: CI automatically calculates next available version

Release Branch Mismatch

Problem: MR targets wrong release branch

Solution: Update target branch:

glab mr update <MR_ID> --target-branch release/v0.3.x

Core Projects Out of Sync

Problem: Core projects have different versions

Solution: Trigger synchronized release

Getting Help

  1. Check documentation in this directory
  2. Review CI/CD pipeline logs
  3. Validate commits: echo "feat: test" | npx commitlint
  4. Test semantic-release: npx semantic-release --dry-run
  5. Contact tech lead for complex issues

Resources

External Documentation

Internal Documentation

Contributing

Improving Documentation

To improve this documentation:

  1. Create issue with suggested changes
  2. Follow standard workflow
  3. Submit MR with updates
  4. Request review from tech lead

Reporting Issues

Found a problem with versioning or releases?

  1. Create issue with versioning label
  2. Include:
    • What happened
    • What you expected
    • Steps to reproduce
    • CI/CD logs if applicable

Changelog

This documentation follows Keep a Changelog format.

[1.0.0] - 2026-01-08

Added

  • Initial versioning documentation
  • Semantic versioning guide
  • Automated version bumping guide
  • Release branch strategy
  • Changelog generation guide
  • GitLab releases guide
  • Conventional commits guide
  • Multi-project versioning guide

Last Updated: 2026-01-08 Maintainer: Agent Platform Team Contact: tech-lead@agent-platform.io