API Versioning Strategy

How AgenticGoKit manages versions, stability, and breaking changes.

Version Structure

AgenticGoKit follows semantic versioning with the following structure:

v<major>.<minor>.<patch>[-<prerelease>]

Examples:
- v1.0.0        (stable release)
- v1.2.3        (stable with patches)
- v1beta        (beta version)
- v2alpha       (alpha version)

Version Stages

Stage	Stability	Breaking Changes	Production Use
alpha	Experimental	Frequent	Not recommended
beta	Stabilizing	Possible	Acceptable
stable	Production-ready	Rare, with migration path	Recommended

Current Versions

v1beta (Current Recommended)

Status: Beta - Production-acceptable

Import Path:

import "github.com/agenticgokit/agenticgokit/v1beta"

Stability Guarantee:

API surface is mostly stable
Minor breaking changes possible with deprecation notices
All breaking changes documented in release notes
Migration guides provided for breaking changes
Security and bug fixes backported

Lifecycle:

Current: Active development and support
After v1.0 release: 6 months maintenance
After maintenance: Legacy status (security fixes only)

core/vnext (Legacy)

Status: Deprecated

Import Path:

import "github.com/agenticgokit/agenticgokit/core/vnext"

Stability Guarantee:

No new features
Critical bug fixes only
Security updates until EOL

Lifecycle:

Current: Maintenance mode
Support ends: 6 months after v1.0 release
After EOL: No updates

Migration: See Migration Guide

Breaking Changes Policy

What is a Breaking Change?

A breaking change is any modification that requires users to update their code:

Removing public APIs
Changing function signatures
Renaming types or functions
Changing behavior of existing APIs
Changing import paths

How We Handle Breaking Changes

Beta Versions (v1beta)

Process:

Announcement - Breaking change announced in GitHub discussions
Deprecation Period - Old API marked deprecated (minimum 1 release cycle)
Migration Guide - Step-by-step guide provided
Release - Breaking change shipped with clear release notes

Timeline:

Release N:   Deprecation notice + new API introduced
Release N+1: Old API still works with warnings
Release N+2: Old API removed (breaking change)

Stable Versions (v1.x)

Process:

Avoid if possible - Breaking changes avoided in stable versions
Major version bump - Breaking changes only in major versions (v1 → v2)
Long deprecation - Minimum 6-month deprecation period
Parallel support - Old and new APIs coexist during transition

Example:

v1.0: Current API
v1.5: New API introduced, old API deprecated
v1.x: Both APIs work for 6+ months
v2.0: Old API removed

Deprecation Process

Marking APIs as Deprecated

// Deprecated: Use NewBuilder instead.
// This function will be removed in v2.0.
func CreateAgent(name string) *Agent {
    // Implementation
}

// NewBuilder creates an agent using the builder pattern.
// Recommended replacement for deprecated CreateAgent.
func NewBuilder(name string) *Builder {
    // Implementation
}

Deprecation Notice Format

// Deprecated: [Reason]
// Use [Replacement] instead.
// This will be removed in [Version].

User Communication

Deprecations are communicated via:

Code Comments - GoDoc deprecation notices
Release Notes - Explicit mention in changelog
GitHub Discussions - Advance notice thread
Migration Guides - Detailed migration instructions
Runtime Warnings - Log warnings for deprecated APIs (where feasible)

Compatibility Guarantees

v1beta Guarantees

✅ What We Promise:

Core functionality remains stable
Bug fixes don't break existing code
Performance improvements are transparent
Security patches are non-breaking when possible

⚠️ What May Change:

New features may be added
Minor API adjustments with deprecation notices
Error messages and types may be enhanced
Internal implementation may change

❌ No Guarantee:

Experimental features (marked explicitly)
Internal packages (not in public API)
Undocumented behavior

v1.0+ Guarantees

✅ What We Promise:

Public API is stable across minor versions (v1.x)
No breaking changes within major version
Security and bug fixes for 2+ years after major release
Clear migration path for major version upgrades

Version Support Timeline

v1beta:    Active (Current)
           ↓
v1.0:      Stable Release
           ├─ v1.x: Active development (24+ months)
           ├─ Security fixes (12+ months after v2.0)
           └─ EOL
           
v1beta:    Maintenance (after v1.0)
           ├─ Critical bugs (6 months)
           ├─ Security fixes (6 months)
           └─ EOL (6 months after v1.0)

Support Phases

Phase	Duration	Updates	Example
Active	Indefinite	Features, bugs, security	v1beta (current)
Maintenance	6 months	Critical bugs, security	core/vnext
Security	6 months	Security only	-
EOL	Forever	None	-

Choosing a Version

For New Projects

Recommendation: v1beta

import "github.com/agenticgokit/agenticgokit/v1beta"

Reasons:

Modern, clean API
Active development
Best documentation
Production-acceptable stability
Will become v1.0 (seamless upgrade)

For Existing Projects (Legacy)

Option 1: Migrate to v1beta (Recommended)

See Migration Guide for step-by-step instructions.

Benefits:

Modern features
Better performance
Long-term support
Continued updates

Option 2: Stay on Legacy

Acceptable if:

Project is in maintenance mode
No new features needed
Will be decommissioned within 6 months

API Stability Markers

Stable

// Stable: This API is production-ready and will not change
// in breaking ways within the current major version.
func NewBuilder(name string) *Builder

Beta

// Beta: This API is mostly stable but may have minor changes
// with deprecation notices. Production-acceptable.
func WithExperimentalFeature() *Builder

Experimental

// Experimental: This API is under active development and may
// change significantly. Not recommended for production use.
func ExperimentalFeature() error

Internal

// Internal: This package is for internal use only and may
// change without notice. Do not import.
package internal

Release Process

Version Bumping

Patch Release (v1.0.x):

Bug fixes
Security patches
Documentation improvements
No API changes

Minor Release (v1.x.0):

New features (backward compatible)
Deprecations (with notices)
Performance improvements
API additions (no removals)

Major Release (vX.0.0):

Breaking changes
API removals (after deprecation)
Major architectural changes
Requires migration

Release Cadence

Patch releases: As needed (bug fixes)
Minor releases: Monthly or as needed
Major releases: Yearly or as needed

Backward Compatibility

What We Maintain

✅ Guaranteed Compatibility:

Function signatures
Type definitions
Package imports
Documented behavior
Configuration formats

⚠️ Best Effort:

Error messages
Log output
Performance characteristics
Internal implementation

❌ No Guarantee:

Undocumented features
Internal packages
Test helpers
Examples (may be updated)

Testing Compatibility

We test backward compatibility via:

Regression Tests - Existing tests must pass
API Compatibility Checker - Tools detect breaking changes
Integration Tests - Real-world usage patterns validated
Community Feedback - Beta releases for early testing

Experimental Features

Definition

Experimental features are:

New functionality under evaluation
May change based on feedback
Not subject to normal stability guarantees
Clearly marked in documentation

Usage Guidelines

Acceptable for experimentation:

// Try new features in development
agent, _ := v1beta.NewBuilder("Agent").
    WithExperimentalFeature(). // OK for testing
    Build()

Not recommended for production:

// Avoid in production systems
agent, _ := v1beta.NewBuilder("ProductionAgent").
    WithExperimentalFeature(). // Risky - may change
    Build()

Graduation Process

Experimental → Beta → Stable

Experimental: Initial release, gather feedback
Beta: API stabilized, minor changes possible
Stable: API locked, stability guaranteed

Migration Support

Resources

Migration Guide - Complete migration instructions
Migration Tutorials - Step-by-step guides
GitHub Discussions - Community help
Release Notes - Detailed changelogs

Migration Timeline

Standard Timeline:

Deprecation Notice → 6 months → Removal

Emergency Timeline (security):

Security Issue → Patch Release → 3 months → Removal

Security Updates

Policy

Security issues receive immediate attention
Patches released for supported versions
Coordinated disclosure process
Security advisories published

Supported Versions for Security Patches

Version	Security Support
v1beta (current)	✅ Active
core/vnext	✅ Until v1.0 + 6 months
v1.0+	✅ 12 months after next major

Reporting Security Issues

Do not open public issues for security vulnerabilities.

Email: security@agenticgokit.dev

Questions & Support

Version Questions: GitHub Discussions
Bug Reports: GitHub Issues
Feature Requests: GitHub Discussions
Migration Help: Migration Guide

Next Steps

Getting Started - Start building with v1beta
Migration Guide - Migrate from legacy APIs
Roadmap - Planned features and timeline

API Versioning Strategy ​

Version Structure ​

Version Stages ​

Current Versions ​

v1beta (Current Recommended) ​

core/vnext (Legacy) ​

Breaking Changes Policy ​

What is a Breaking Change? ​

How We Handle Breaking Changes ​

Beta Versions (v1beta) ​

Stable Versions (v1.x) ​

Deprecation Process ​

Marking APIs as Deprecated ​

Deprecation Notice Format ​

User Communication ​

Compatibility Guarantees ​

v1beta Guarantees ​

v1.0+ Guarantees ​

Version Support Timeline ​

Support Phases ​

Choosing a Version ​

For New Projects ​

For Existing Projects (Legacy) ​

API Stability Markers ​

Stable ​

Beta ​

Experimental ​

Internal ​

Release Process ​

Version Bumping ​

Release Cadence ​

Backward Compatibility ​

What We Maintain ​

Testing Compatibility ​

Experimental Features ​

Definition ​

Usage Guidelines ​

Graduation Process ​

Migration Support ​

Resources ​

Migration Timeline ​

Security Updates ​

Policy ​

Supported Versions for Security Patches ​

Reporting Security Issues ​

Questions & Support ​

Next Steps ​