Semantic Versioning Policy

Semantic Versioning Policy

QQQ follows Semantic Versioning 2.0.0 to ensure predictable releases and safe upgrades for users.

Quick Links

• Home
• Branching & Versioning
• Release Flow
• Changelog & Tagging

Version Bump Criteria

PATCH (X.Y.Z+1)

When: Backward-compatible bug fixes and minor improvements.

Examples:

• Bug fixes that don't change public APIs
• Security patches and vulnerability fixes
• Performance optimizations with no behavior changes
• Documentation corrections and clarifications
• Dependency updates that don't break compatibility

MINOR (X.Y+1.0)

When: New backward-compatible functionality.

Examples:

• New features that extend existing APIs
• New backend modules, middleware components
• New dashboard widgets and UI components
• Enhanced configuration options
• New utility classes and helper methods

MAJOR (X+1.0.0)

When: Incompatible API changes or breaking modifications.

Examples:

• Breaking changes to public APIs
• Removal of deprecated features
• Incompatible configuration changes
• Database schema changes that break existing data
• Major architectural changes

Public API Surfaces

SemVer applies to these public interfaces that users depend on:

• Java APIs: Public classes, methods, interfaces, constants, exceptions
• Configuration: Environment variables, config files, database parameters
• Network Interfaces: REST endpoints, gRPC services, WebSocket formats
• CLI Commands: Command names, arguments, output formats
• Database Schemas: Table structures, indexes, stored procedures

Backward Compatibility Guidelines

Breaking Changes

• Method signature changes (parameters, return types, exceptions)
• Required new configuration properties
• Different output formats or behavior
• Removal of public APIs or features

Safe Changes

• Internal implementation refactoring
• Performance improvements with same results
• New optional features with defaults
• Documentation updates and clarifications

Deprecation Policy

QQQ follows a two-version deprecation policy:

1. Mark as deprecated with @Deprecated annotation
2. Keep available for at least one major version
3. Remove in next major version

@Deprecated(since = "1.5.0", forRemoval = true)
public class OldClass {
    // Will be removed in 3.0.0
}

See Also

• Release Flow - Release workflow
• Branching & Versioning - Branching strategy