The Version Support Challenge
Every software project must answer: how many versions do we support simultaneously? Support too many and resource burden becomes crushing. Support too few and users get abandoned when critical bugs appear. CleanStart's answer provides support for exactly 4 concurrent major versions (N, N-1, N-2, N-3) with automatic cascade patching across all versions.
Why N to N-3?
Four concurrent versions balances several competing needs. Assuming annual releases, the version timeline progresses as follows: In Year 0, CleanStart releases Version N (e.g., v2.0.0). At this time, Version N receives active development, Version N-1 receives critical and security patches only, Version N-2 receives security patches only, and Version N-3 receives security patches only.
In Year 1, CleanStart releases Version N+1 (e.g., v3.0.0). At this time, Version N+1 receives active development, Version N receives critical and security patches only, Version N-1 receives security patches only, Version N-2 receives security patches only, and Version N-3 reaches end of life and is no longer supported.
In Year 2, CleanStart releases Version N+2. At this time, Version N+2 receives active development, Version N+1 receives critical and security patches only, Version N receives security patches only, and Version N-1 reaches end of life.
The benefits of this approach are substantial. Users have approximately 4 years to upgrade (N released, then N+1, N+2, N+3). Companies with slow deployment cycles stay protected. Security patches are applied to all versions automatically. The development team doesn't spread too thin supporting old versions.
Vulnerability Cascade Across Versions
When a vulnerability is discovered, CleanStart automatically patches all supported versions. An OpenSSL CVE is discovered, and a patch is released (e.g., 1.1.1y). CleanStart detects the patch and applies it across all supported versions: Version N (active development branch), Version N-1 (critical patch branch), Version N-2 (maintenance branch), and Version N-3 (long-term support branch). Each version automatically rebuilds all dependent packages, ensuring all 19,200 images are updated across all four versions.
Version-Specific Build Pipelines
CleanStart maintains separate build pipelines for each version. The repository structure includes the main branch for Version N+1 development, release/v3.0 for Version N active development, release/v2.1 for Version N-1 patch releases, release/v2.0 for Version N-2 patch releases, and release/v1.0 for Version N-3 patch releases. Build pipelines are version-specific: Version N+1 builds everything, Version N builds everything, Version N-1 builds critical patches only, Version N-2 builds security patches only, and Version N-3 builds security patches only.
Configuration Matrix
Each version has version-specific build parameters:
versions: v4.0.0: # N (active development) status: development feature_development: true performance_optimization: true api_breaking_changes: true node_versions: [18, 20] python_versions: [3.11, 3.12] go_versions: [1.21, 1.22] v3.1.0: # N-1 (critical patches) status: critical_patch_only feature_development: false performance_optimization: false api_breaking_changes: false node_versions: [18] python_versions: [3.11] go_versions: [1.20] backport_policy: critical_and_security v3.0.0: # N-2 (security patches) status: maintenance backport_policy: security_only support_duration: 18_months_from_release eol_date: 2025-06-30 v2.0.0: # N-3 (security patches, long-term support) status: long_term_support backport_policy: security_only support_duration: 36_months_from_release eol_date: 2026-06-30Patch Release Workflow
Patch Levels
In semantic versioning (e.g., v3.1.4), the rightmost number is the patch number (representing bug fixes and security patches), the middle number is the minor version (representing compatible features), and the leftmost number is the major version (representing breaking changes). The progression follows this pattern: v3.0.0 through v3.0.3 are patch releases (varying only the rightmost number), v3.0.x progresses to v3.1.0 through v3.1.2 are minor releases (varying the middle number), and v3.x.x progresses to v4.0.0 as a major release (varying the leftmost number).
Automatic Backporting
When a security patch is merged to main (N+1), an automated backport system activates. The system cherry-picks the commit to v4.0 (Version N), tests it in the v4.0 context, and auto-merges if tests pass. It then cherry-picks the commit to v3.1 (Version N-1), resolves any conflicts, tests in the v3.1 context, and creates a pull request for human review. It cherry-picks to v3.0 (Version N-2), resolves conflicts, tests, and creates a PR for review. Finally, it cherry-picks to v2.0 (Version N-3), resolves conflicts, tests, and creates a PR for review. All versions are patched within 24 hours. The system automatically handles 80% of backports; complex conflicts requiring human review are escalated.
Dependency Version Compatibility
Each version has its own compatible dependency versions:
v4.0.0: # N dependencies: openssl: ">=3.0.0" nodejs: ">=18.0.0" go: ">=1.21.0" glibc: ">=2.35" features: tls13: enabled http3: experimental v3.1.0: # N-1 dependencies: openssl: ">=1.1.1" nodejs: ">=16.0.0" go: ">=1.20.0" glibc: ">=2.31" features: tls13: enabled http3: disabled v3.0.0: # N-2 dependencies: openssl: ">=1.1.0" nodejs: ">=14.0.0" go: ">=1.19.0" glibc: ">=2.31" features: tls13: disabled http3: disabled v2.0.0: # N-3 dependencies: openssl: ">=1.1.0" nodejs: ">=12.0.0" go: ">=1.16.0" glibc: ">=2.29" features: tls13: disabled http3: disabledThis allows users on old systems to run v2.0.0 while new systems get v4.0.0.
Security Patching Example: OpenSSL Update
OpenSSL 1.1.1y has a critical vulnerability. CleanStart responds with a timeline that begins at T+0.0h when vulnerability is disclosed and OpenSSL patches released.
At T+0.5 hours, CleanStart detects the update and begins analyzing its impact on all 4 supported versions, determining which versions are affected, and triggering rebuilds. At T+1.0 hour, rebuilds complete for all versions: v4.0.0 uses OpenSSL 3.0.x (not affected, no rebuild needed), v3.1.0 uses OpenSSL 1.1.1 (rebuilds to 1.1.1y), v3.0.0 uses OpenSSL 1.1.1 (rebuilds to 1.1.1y), and v2.0.0 uses OpenSSL 1.1.0 (not affected, no rebuild needed). At T+1.5 hours, testing completes: v3.1.0 has 2,100 images tested (pass), and v3.0.0 has 1,800 images tested (pass). At T+2.0 hours, security patches are released: v3.1.3 (critical security patch) and v3.0.4 (critical security patch). At T+2.5 hours, deployment begins: v3.1.3 deploys to 3,900 production images and v3.0.4 deploys to 1,800 production images. At T+4.0 hours, all affected versions are fully patched.
Key insight: OpenSSL v3.0.0 (used by v4.0.0) wasn't affected, so no rebuild needed. Older v2.0.0 uses the earlier OpenSSL 1.1.0 branch which had a different patch history.
EOL (End of Life) Coordination
As versions age, they move through the lifecycle. A version released on 2023-06-30 follows this timeline: it enters active development (Version N) from 2023-06-30 to 2024-06-30 (1 year), transitions to critical patch only (Version N-1) from 2024-06-30 to 2024-12-31 (7 months), transitions to security patches only (Version N-2) from 2024-12-31 to 2025-12-31 (1 year), transitions to long-term support (Version N-3) from 2025-12-31 to 2026-06-30 (7 months), with end-of-life announced on 2025-12-01 (6 months before EOL), and reaches end-of-life on 2026-06-30.
The user upgrade timeline progresses as follows: all users start on v2.0.0 on 2023-06-30 (the new release), some users upgrade to v3.0.0 on 2024-06-30 when it becomes available, v2.0.0 moves to long-term support on 2025-06-30 and users must upgrade within one year, an end-of-life announcement is made on 2025-12-01 stating that v2.0.0 support ends on 2026-06-30, and the version officially reaches end-of-life on 2026-06-30.
LTS (Long-Term Support): N-3 versions get extended support timelines for users who can't upgrade frequently.
Version Pinning Best Practices
CleanStart applications should pin to version families:
# Recommended: Pin to major versionversion: "^3.0.0" # Accepts 3.x.x, rejects 4.0.0 # Also acceptable: Pin to minor versionversion: "~3.1.0" # Accepts 3.1.x, rejects 3.2.0 # Not recommended: Pin to exact versionversion: "3.0.4" # Miss security patches! # Never do this: Unversioned (accepts anything)version: "*" # Dangerous, unpredictableTesting Across Version Matrix
CleanStart's CI/CD system tests every change against all 4 supported versions. When a developer submits a change to main (v4.0.0), CleanStart's CI/CD system runs a comprehensive test matrix. The system runs v4.0.0 tests for the new development version, v3.1.x tests for the current release, v3.0.x tests for the previous release, and v2.0.x tests for the long-term support version. If all versions pass, the system merges the change. If any version fails, the system blocks the merge and notifies the developer. This approach ensures that bug fixes in newer versions do not cause regressions in older supported versions.
Version-Specific Documentation
Each version has its own documentation. A latest symlink points to v4.0.0. The v4.0.0 documentation includes an API reference (documenting new endpoints), a migration guide (for upgrading from v3.1.0), and a changelog (documenting breaking changes). The v3.1.0 documentation includes a stable API reference, documentation of applied security patches, and a changelog of bug fixes. The v3.0.0 documentation includes an API reference and security patch documentation. The v2.0.0 documentation includes an API reference and an end-of-life notice (documenting the approaching EOL date).
Users can reference docs for their specific version, avoiding confusion.
Version Migration Path
When upgrading between versions, users should understand the compatibility implications. v2.0.0 (LTS) → v3.0.0: This upgrade includes breaking changes (API v1 to v2), with approximately 95% code compatibility. Users should follow the detailed migration guide and test for 2 weeks before upgrading. It's recommended to keep v2.0.0 running alongside during the transition for safety.
v3.0.0 → v3.1.0: This minor version upgrade has no breaking changes and maintains 100% compatibility. The upgrade is auto-compatible and can happen instantly with no downtime needed.
v3.1.0 → v4.0.0: This major version upgrade includes major API changes with approximately 80% code compatibility. A complete migration guide is provided, and testing is recommended for 1 month before upgrading. Rollback requires downtime to revert.
The version matrix ensures users have a clear upgrade path while maintaining protection across all supported versions.