Skip to content

Libraries Lifecycle

This document describes the lifecycle for shared libraries, focusing on versioning, compatibility, and deprecation. It is written for engineers maintaining ConnectSoft.Extensions.* libraries.

ConnectSoft libraries follow semantic versioning and maintain backward compatibility within major versions. Understanding the lifecycle helps maintainers make versioning decisions and plan deprecations.

Important

Libraries must maintain backward compatibility within major versions. Breaking changes require a major version bump and careful migration planning.

Lifecycle States

State Description Versioning Support
Development Active development Pre-release versions (0.x.x) No support
Stable Production-ready Major versions (1.x.x, 2.x.x) Full support
Maintenance Bug fixes only Patch versions (x.x.1, x.x.2) Full support
Deprecated Scheduled for removal Final versions Migration support only
End of Life No longer supported N/A No support

Versioning Rules

Semantic Versioning (SemVer)

Follow Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

  • MAJOR - Breaking changes (incompatible API changes)
  • MINOR - Backward-compatible features (new functionality)
  • PATCH - Backward-compatible bug fixes

Version Mapping

Change Type Version Bump Examples
Breaking Change MAJOR (1.0.0 → 2.0.0) Removed API, changed method signature, removed dependency
New Feature MINOR (1.0.0 → 1.1.0) New method, new option, new functionality
Bug Fix PATCH (1.0.0 → 1.0.1) Bug fix, performance improvement, documentation

Pre-Release Versions

  • 0.x.x - Development, not stable
  • 1.0.0-rc.1 - Release candidate
  • 1.0.0-beta.1 - Beta version
  • 1.0.0-alpha.1 - Alpha version

Breaking Changes Policy

What Constitutes Breaking Changes

  • Removed APIs - Removing public APIs
  • Changed Signatures - Changing method signatures
  • Changed Behavior - Changing behavior in incompatible ways
  • Removed Dependencies - Removing required dependencies
  • Changed Defaults - Changing default behavior in incompatible ways

Breaking Change Process

  1. ADR Required - Create ADR documenting breaking change
  2. Migration Guide - Provide migration guide
  3. Deprecation Notice - Deprecate in previous major version (if possible)
  4. Major Version Bump - Bump major version
  5. Communication - Communicate breaking changes clearly

See: Decision Records Process for ADR process.

Migration Guides

  • Step-by-Step - Provide step-by-step migration instructions
  • Code Examples - Include code examples
  • Breaking Changes List - List all breaking changes
  • FAQ - Address common migration questions

Deprecation and Support Windows

Deprecation Policy

  • Advance Notice - Minimum 6 months advance notice
  • Obsolete Attributes - Mark deprecated APIs with [Obsolete] attributes
  • Documentation - Document deprecation in release notes
  • Migration Support - Provide migration support and guidance

Support Windows

Version Type Support Duration Support Level
Current Major Full support Bug fixes, features, security updates
Previous Major 12 months Security updates, critical bug fixes only
Deprecated 6 months Migration support only
End of Life No support No updates, no support

Version Support Matrix

Library Version Release Date Support Until Status
2.x.x Current TBD Full support
1.x.x Previous 12 months after 2.0.0 Security updates only
0.x.x Pre-release N/A No support