semver

Semantic Versioning (SemVer) Guide

Overview

Semantic Versioning (SemVer) is a formal convention for software version numbers that conveys meaning about the underlying changes. The Agent Platform follows SemVer 2.0.0 specification to ensure predictable version progression and clear communication about changes.

Version Format

MAJOR.MINOR.PATCH

Example: v0.3.5
         ‚ ‚ ‚
         ‚ ‚  PATCH: Bug fixes (backward compatible)
         ‚  MINOR: New features (backward compatible)
          MAJOR: Breaking changes (incompatible API changes)

Version Number Rules

Format: X.Y.Z where X, Y, and Z are non-negative integers
No Leading Zeros: Each element must NOT contain leading zeros
Numeric Increase: Each element MUST increase numerically
Immutable: Once a versioned package is released, the contents MUST NOT be modified

When to Increment Each Version

PATCH (0.0.X)

Increment when: Making backward-compatible bug fixes

Examples:

Fixing a runtime error
Correcting incorrect behavior
Resolving memory leaks
Security patches that don't change the API

Conventional Commits:

git commit -m "fix: resolve memory leak in agent runtime"
git commit -m "fix: correct authentication token validation"

MINOR (0.X.0)

Increment when: Adding functionality in a backward-compatible manner

Examples:

Adding new API endpoints
Adding new optional parameters
Adding new features
Deprecating functionality (marking for future removal)
Substantial internal improvements

Conventional Commits:

git commit -m "feat: add OAuth2 authentication support"
git commit -m "feat: implement distributed tracing"

MAJOR (X.0.0)

Increment when: Making incompatible API changes

Examples:

Removing public API endpoints
Changing required parameters
Changing behavior of existing APIs
Removing deprecated features
Significant architectural changes

Conventional Commits:

git commit -m "feat!: redesign authentication API

BREAKING CHANGE: The /auth endpoint now requires OAuth2 tokens instead of API keys."

Pre-1.0 Versioning (0.x.y)

The Agent Platform currently uses pre-1.0 versioning, which has special rules:

Version 0.x.y Rules

Purpose: Initial development phase
Stability: Public API should NOT be considered stable
Breaking Changes: Anything MAY change at any time
Minor as Major: In 0.x.y, the MINOR version acts as the MAJOR
- 0.x.0 can introduce breaking changes
- 0.x.y (patch) should be bug fixes only

Pre-1.0 Versioning Strategy

0.1.0   - Initial development release
0.2.0   - New features (may include breaking changes)
0.2.1   - Bug fixes
0.2.2   - More bug fixes
0.3.0   - More features (may include breaking changes)
...
1.0.0   - First stable public API release

When to Release 1.0.0

Release version 1.0.0 when:

Public API is stable and committed
Production-ready
Breaking changes will follow strict SemVer rules
Documentation is complete
Security and compliance requirements met

Note: In the Agent Platform, we're targeting v1.0.0 for production-ready release after completing all core features and integrations.

Pre-release Versions

SemVer supports pre-release versions with additional labels:

1.0.0-alpha.1    - Alpha release
1.0.0-beta.1     - Beta release
1.0.0-rc.1       - Release candidate
1.0.0            - Stable release

Pre-release Format

X.Y.Z-<label>.<number>

Examples:
0.3.0-alpha.1
0.3.0-beta.1
0.3.0-rc.1

Pre-release Precedence

Pre-release versions have lower precedence than the normal version:

0.3.0-alpha.1 < 0.3.0-alpha.2 < 0.3.0-beta.1 < 0.3.0-rc.1 < 0.3.0

Build Metadata

Build metadata can be appended with a plus sign:

0.3.0+20260108.sha.5114f85
0.3.0-beta.1+exp.sha.5114f85

Important: Build metadata SHOULD be ignored when determining version precedence.

Agent Platform Versioning Rules

Current Strategy

The Agent Platform uses a release branch model with automatic patch versioning:

main (production releases)
  †
release/v0.3.x (release branch for v0.3.x series)
  †
106-issue-slug (feature branches)

Version Determination

MAJOR.MINOR: Determined by release branch name
- release/v0.1.x † v0.1.0, v0.1.1, v0.1.2...
- release/v0.2.x † v0.2.0, v0.2.1, v0.2.2...
- release/v0.3.x † v0.3.0, v0.3.1, v0.3.2...
PATCH: Auto-incremented by CI/CD on each merge
- First merge to release/v0.3.x † v0.3.0
- Second merge † v0.3.1
- Third merge † v0.3.2

Milestone to Version Mapping

Group Milestones determine target version:

Issue Milestone: v0.3.x
Target Branch:   release/v0.3.x
Released As:     v0.3.0, v0.3.1, v0.3.2... (auto-incremented)

Breaking Change Strategy (Pre-1.0)

Since we're in 0.x.y, breaking changes are allowed in MINOR versions:

0.1.x † Initial features
0.2.x † Core platform features (breaking changes OK)
0.3.x † Integrations & connectors (breaking changes OK)
1.0.x † Production release (breaking changes = MAJOR bump)

Version Comparison

Precedence Rules

Version 1.0.0 > 0.3.5
Version 0.3.5 > 0.3.4
Version 0.3.0 > 0.2.9
Pre-release versions have lower precedence: 0.3.0-alpha.1 < 0.3.0

Comparison Algorithm

1. Compare MAJOR (higher wins)
2. If MAJOR equal, compare MINOR (higher wins)
3. If MINOR equal, compare PATCH (higher wins)
4. If all equal, compare pre-release:
   - No pre-release > has pre-release
   - Compare pre-release identifiers left to right

SemVer and Dependency Management

Specifying Version Ranges

Exact version:

"dependencies": {
  "agent-core": "0.3.5"
}

Caret range (compatible with specified version):

"dependencies": {
  "agent-core": "^0.3.0"  // Allows 0.3.0 <= version < 0.4.0
}

Tilde range (patch-level changes):

"dependencies": {
  "agent-core": "~0.3.0"  // Allows 0.3.0 <= version < 0.4.0
}

Pre-1.0 Dependency Considerations

Warning: ^0.x.y in pre-1.0 is risky because MINOR versions can have breaking changes.

Recommended approach for pre-1.0 dependencies:

"dependencies": {
  "agent-core": "~0.3.0"  // Only allow patch updates
}

Common SemVer Mistakes

Mistake 1: Skipping Versions

Wrong:

v0.1.0 † v0.1.2  (skipped v0.1.1)

Right:

v0.1.0 † v0.1.1 † v0.1.2

Mistake 2: Changing Version Format

Wrong:

v0.1.0 † 0.1.1 † v0.1.2  (inconsistent v prefix)

Right:

v0.1.0 † v0.1.1 † v0.1.2  (consistent v prefix)

Mistake 3: Breaking Changes in PATCH

Wrong:

v1.2.3 † v1.2.4  (but includes breaking API change)

Right:

v1.2.3 † v2.0.0  (breaking change = MAJOR bump)

Mistake 4: Modifying Released Versions

Wrong:

Release v0.3.0, discover bug, fix it, re-release as v0.3.0

Right:

Release v0.3.0, discover bug, fix it, release as v0.3.1

SemVer FAQ

Q: Should I start at 0.1.0 or 0.0.1?

A: Start at 0.1.0. The first version should be 0.1.0 as per SemVer FAQ.

Q: When should I release 1.0.0?

A: When your software is being used in production and you have a stable API that you're committed to maintaining.

Q: Can I have version 0.0.0?

A: No. The minimum version is 0.0.1 or 0.1.0.

Q: What do I do if I accidentally introduce breaking changes in a PATCH release?

A: Release a new version that fixes the problem and restores backward compatibility, or document the breaking change and release a new MAJOR/MINOR version.

Q: How should I handle deprecations?

Document the deprecation
Release as MINOR version (new deprecation warning)
Give users time to migrate
Remove in next MAJOR version

Q: Do I need to follow SemVer for internal projects?

A: It's highly recommended even for internal projects to avoid confusion and enable better dependency management.

SemVer Tools

Version Comparison (Node.js)

const semver = require('semver');

semver.valid('0.3.5');              // '0.3.5'
semver.clean('  =v0.3.5   ');       // '0.3.5'
semver.satisfies('0.3.5', '>=0.3.0 <0.4.0');  // true
semver.gt('0.3.5', '0.3.4');        // true
semver.inc('0.3.5', 'patch');       // '0.3.6'
semver.inc('0.3.5', 'minor');       // '0.4.0'
semver.inc('0.3.5', 'major');       // '1.0.0'

Version Parsing (Shell)

# Extract major version
echo "v0.3.5" | sed 's/v\([0-9]*\)\..*/\1/'  # Output: 0

# Extract minor version
echo "v0.3.5" | sed 's/v[0-9]*\.\([0-9]*\)\..*/\1/'  # Output: 3

# Extract patch version
echo "v0.3.5" | sed 's/v[0-9]*\.[0-9]*\.\([0-9]*\).*/\1/'  # Output: 5

Enforcement in CI/CD

The Agent Platform enforces SemVer through automated checks:

# .gitlab-ci.yml
version-validation:
  stage: validate
  script:
    - |
      # Validate version format
      if ! echo "$CI_COMMIT_TAG" | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
        echo "ERROR: Tag $CI_COMMIT_TAG does not match SemVer format"
        exit 1
      fi
    - |
      # Ensure version is higher than previous
      PREV_VERSION=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "v0.0.0")
      if ! npx semver $CI_COMMIT_TAG -r ">$PREV_VERSION"; then
        echo "ERROR: New version must be greater than $PREV_VERSION"
        exit 1
      fi
  only:
    - tags

Best Practices Summary

DO:

Follow SemVer 2.0.0 specification strictly
Use conventional commits to automate version bumping
Document breaking changes clearly
Test version comparison logic
Use pre-release versions for testing
Start at 0.1.0 for new projects
Release 1.0.0 when production-ready

DON'T:

Skip version numbers
Modify already-released versions
Use inconsistent version formats
Break APIs in PATCH versions (post-1.0)
Release without testing
Use arbitrary version numbers

semver

Semantic Versioning (SemVer) Guide

Overview

Version Format

Version Number Rules

When to Increment Each Version

PATCH (0.0.X)

MINOR (0.X.0)

MAJOR (X.0.0)

Pre-1.0 Versioning (0.x.y)

Version 0.x.y Rules

Pre-1.0 Versioning Strategy

When to Release 1.0.0

Pre-release Versions

Pre-release Format

Pre-release Precedence

Build Metadata

Agent Platform Versioning Rules

Current Strategy

Version Determination

Milestone to Version Mapping

Breaking Change Strategy (Pre-1.0)

Version Comparison

Precedence Rules

Comparison Algorithm

SemVer and Dependency Management

Specifying Version Ranges

Pre-1.0 Dependency Considerations

Common SemVer Mistakes

Mistake 1: Skipping Versions

Mistake 2: Changing Version Format

Mistake 3: Breaking Changes in PATCH

Mistake 4: Modifying Released Versions

SemVer FAQ

Q: Should I start at 0.1.0 or 0.0.1?

Q: When should I release 1.0.0?

Q: Can I have version 0.0.0?

Q: What do I do if I accidentally introduce breaking changes in a PATCH release?

Q: How should I handle deprecations?

Q: Do I need to follow SemVer for internal projects?

SemVer Tools

Version Comparison (Node.js)

Version Parsing (Shell)

Enforcement in CI/CD

Best Practices Summary

Resources

See Also