Purpose

When you integrate CleanStart into your CI/CD pipelines, admission controllers, security scanning tools, monitoring systems, and policy frameworks, you need confidence that these integrations won't break unexpectedly. This document defines the backward compatibility commitments that CleanStart makes to customers.

In short: We promise that interfaces (container image tags, CLI tools, API endpoints) won't change in ways that require code changes or operational adjustments—unless we give you months of notice.

Audience

This policy applies to DevOps engineers integrating CleanStart into Kubernetes clusters, security teams that scan and verify CleanStart images, CTOs and architects making long-term infrastructure decisions, compliance teams evaluating vendor support commitments, and anyone building tooling that depends on CleanStart. All of these stakeholders require clarity about which interfaces will remain stable and which may change.

Versioning Strategy

Container Image Versioning

CleanStart uses semantic versioning for all container images: MAJOR.MINOR.PATCH

Examples: registry.cleanstart.com/cleanstart/python:3.12.1 (MAJOR=3, MINOR=12, PATCH=1), registry.cleanstart.com/cleanstart/go:1.22.3, and registry.cleanstart.com/cleanstart/nodejs:22.4.0.

Version Increment Rules

A PATCH bump (e.g., 3.12.0 → 3.12.1) occurs when CleanStart applies security patches to fix CVEs, implements bug fixes that don't change behavior, performs internal optimizations, or updates packages within the same language version. These changes are fully backward compatible within application code; you can deploy the new patch without modifying your application.

A MINOR bump (e.g., 3.12 → 3.13) occurs when new language runtime features are introduced, package versions are updated, or performance improvements are made. This level of change may require application code modifications—for example, new compiler warnings, stricter linting rules, or compatibility adjustments.

A MAJOR bump (e.g., 3 → 4) is reserved for breaking runtime changes, incompatible language version transitions, or new security model implementations. This level of change may require significant application refactoring and should be treated as a substantial upgrade with careful planning.

Image Tag Immutability

Once published, a tag and its corresponding digest (SHA256 hash) never change. The tag registry.cleanstart.com/cleanstart/python:3.12.1 points to exactly one image with digest sha256:abc123... and will continue to point to that same image even a year from now. This immutability matters because it enables reproducible deployments where the same image deployed always produces the same behavior, creates an audit trail that proves which exact image was in production at any given time, and provides security by making it impossible to secretly replace an image with a backdoored version.

Image tags follow a consistent naming convention. The major tag (e.g., python:3) always points to the latest version within that major version (3.x). The minor tag (e.g., python:3.12) points to the latest patch version within that minor version (3.12.x). The patch tag (e.g., python:3.12.1) points to an exact version with no movement. The latest tag (python:latest) always points to the newest version available, but is not recommended for production use due to its mutability.

Digest Pinning (Recommended)

For production deployments, pin to exact digest instead of tag:

apiVersion: apps/v1kind: Deploymentmetadata:  name: apispec:  template:    spec:      containers:      - name: api        # Pin to specific version AND digest for maximum reproducibility        image: registry.cleanstart.com/cleanstart/python:3.12.1@sha256:abc123def456

Digest pinning provides several benefits that make it ideal for production environments. Reproducible builds are guaranteed because even if a tag is updated, your digest reference never changes, ensuring the exact same image is deployed every time. Accidental updates are prevented because while a tag may move to a newer version, your digest-pinned reference stays locked to the specific image you selected. Audit compliance is achieved because you can prove exactly what code was running at any point in time by referencing the immutable digest.

CLI Tool Versioning

CleanStart CLI tools (cleanimg-init, cleanimg-customize, clnstrt-cli, etc.) use semantic versioning.

Version Compatibility Within Major Version

Within the same major version (e.g., v2.x), we guarantee backward compatibility across multiple dimensions. All subcommands remain in place and are never removed—if a subcommand exists in v2.0, it continues to exist in v2.5 and beyond. All long-form flags remain stable (e.g., --output stays forever), output formats remain structured in JSON or YAML, and exit codes remain consistent so your automation doesn't break.

Changes are strictly additive within a major version. New subcommands may be added as features expand. New flags may be added, but they are always optional—existing scripts continue to work without modification. New output fields may appear in JSON responses, but old fields remain in place so your parsing logic continues to function.

Examples of compatible changes within v2.x illustrate this principle clearly. The command cleanimg-init --output image.tar works in v2.0, and in v2.5, you can optionally add --compression-level 5, but the old command still works unchanged. Similarly, cleanimg-customize --signature-type cosign remains valid across versions, but in v2.6, the option is extended to support --signature-type cosign,notary while still accepting the original values.

Examples of incompatible changes are reserved exclusively for major version bumps. The flag rename from cleanimg-init --output to cleanimg-init --output-file is a breaking change and only happens in a major bump like v2.x → v3.0. Subcommand removals or renames, such as changing cleanimg build <image> to cleanimg init <image>, are also breaking changes that require a major version bump.

Deprecation of Features

If we need to remove or change something, the process follows a carefully structured timeline to minimize disruption. During month 0, the deprecation notice begins. The feature is marked as deprecated in the documentation, the CLI shows a deprecation warning when used (for example: "Warning: --old-flag is deprecated. Use --new-flag instead."), and the API documentation is updated with deprecation markers. A blog post explaining the deprecation and providing the migration path is published.

During months 1 through 5, the feature continues to work normally while the 6-month countdown period runs. The support team proactively helps users migrate to the new approach, and community forums discuss migration strategies.

In month 6, a final notice is issued. The CLI displays a final deprecation warning with the message "This feature will be removed in v3.0" (or the next major version), and escalated communication is sent to affected users.

Starting in month 7, the feature is removed only in a major version bump (e.g., v2 → v3). The previous major version continues receiving critical patches for an additional 12 months after the new major version launches.

During months 7 through 19, the v2.x version continues to receive critical security patches but does not receive new features. This extended support window gives users time to upgrade without feeling rushed.

Example timeline illustrates this process: In 2025-01, v2.0 is released. By 2025-03, deprecation is announced for --old-flag. From 2025-04 through 2025-08, the deprecation period runs for 6 months. In 2025-09, v3.0 is released and --old-flag is removed. From 2025-09 through 2026-09, v2.x receives critical patches only. By 2026-10, v2.x reaches end-of-life.

API Versioning

CleanStart provides APIs for programmatic access (REST, GraphQL, etc.). All APIs are versioned in the URL path.

URL Versioning

https://api.clnstrt.dev/api/v1/images         # API v1https://api.clnstrt.dev/api/v2/images         # API v2

Version Support Timeline

v1 launched in January 2024 and v2 launched in January 2025. Version v1 will be supported until January 2027 (24 months after v2 launch), and v2 will be supported until January 2029 (24 months after v3 launch, whenever v3 exists).

Backward Compatibility Within Major Version

Within the same API major version (e.g., v1.x), we guarantee strict compatibility rules. Existing endpoints are never removed or changed. Existing response fields remain in place and continue to work. Existing request parameters (those marked as required) stay required and don't change their meaning.

New endpoints can be added to expand functionality. New response fields may appear in subsequent versions; the old fields always remain present so code that expects v1.0 responses works perfectly with v1.7. New optional request parameters can be introduced to provide additional functionality without breaking existing calls.

Example API response evolution within v1 shows how this works in practice. The v1.0 response contains three fields: id, version, and size. By v1.5, a new field sbom is added (marked with a comment that it's backward compatible), but all three original fields remain. By v1.7, two more fields signature_verified and vulnerability_count are added. Your code expecting the v1.0 response works perfectly with v1.7 because old fields are still there—your code simply ignores the new fields.

// v1.0 response{  "id": "python:3.12",  "version": "3.12.1",  "size": 50331648} // v1.5 response (compatible){  "id": "python:3.12",  "version": "3.12.1",  "size": 50331648,  "sbom": { ... }        // new field, backward compatible} // v1.7 response (still compatible){  "id": "python:3.12",  "version": "3.12.1",  "size": 50331648,  "sbom": { ... },  "signature_verified": true,  // new field  "vulnerability_count": 0     // new field}

What Changes Between Major Versions

Breaking changes only happen in major version bumps. When moving from API v1 to v2, the URL changes from /api/v1/ to /api/v2/, the response structure may change significantly, required parameters may be different, and authentication mechanisms may change.

When this happens, CleanStart provides minimum 6 months notice before a major version becomes unavailable. A comprehensive migration guide is provided to help users transition. Version v1 remains available for 24 months in parallel with v2, giving customers ample time to upgrade. The support team actively helps with migration questions and issues.

Image Feature Stability

What Won't Change (within major version)

Within the same major version (e.g., 3.x), certain image features are guaranteed not to change. The security posture is locked in: the image will always be shell-less with no /bin/sh, will always have a read-only root filesystem, will always run as UID 65532 (non-root), and if FIPS 140-3 mode is enabled, it stays enabled.

Verification artifacts maintain their format and count. Cosign signatures use the standard OpenContainer Image Signing format. SBOMs are generated in SPDX 3.0 or CycloneDX 1.4 formats. SLSA Level 4 provenance is provided in the standard SLSA format. The image includes 11 verification artifacts, and this count may increase in future versions but will not decrease.

Entrypoint behavior is stable. The image entrypoint remains the same across patch and minor versions. The default working directory remains the same. Default environment variables remain the same.

Example guarantees for python:3.x demonstrate this stability: when you run docker run registry.cleanstart.com/cleanstart/python:3.12 across python:3.11, python:3.12, and python:3.13, the behavior is consistent. The Python REPL starts with the same behavior. The root filesystem is always read-only. The container always runs as UID 65532.

What May Change (with notice)

Certain aspects may change within a major version but only with deprecation notice. Package versions receive security updates (e.g., OpenSSL 3.1 → 3.2). These updates rarely cause issues but may have behavioral differences, and updates are always documented in release notes.

Image size may shrink through optimization or rarely grow if new features are added. Image size is a soft target rather than a guarantee. However, significant growth of 50MB or more requires a deprecation notice.

Default resource recommendations may change if cloud providers change their pricing or performance profiles. Your specifically-set CPU and memory limits unchanged unless you choose to update them.

New CLI tools in the image may be installed (e.g., a new language package manager). Your application is unaffected by these additions, but more tools become available for your use if needed.

Feature Deprecation Process

When CleanStart needs to deprecate a feature (CLI flag, API field, image tool):

Step 1: Deprecation Notice (Month 0)

The feature is documented as deprecated in release notes. The CLI shows a warning when the feature is used: ⚠️ --old-flag is deprecated, use --new-flag. API documentation is marked with deprecation notices. A blog post is published explaining the deprecation reason and providing migration paths.

Step 2: Active Support (Months 1–5)

The feature continues to work normally during this 6-month countdown period. The support team proactively reaches out to help users migrate. Community forums discuss migration strategies and best practices.

Step 3: Final Notice (Month 6)

A final deprecation warning is issued in CLI output and logs. The message states "This feature will be removed in v3.0" (or the next major version). Escalated communication is sent to affected users highlighting the upcoming deadline.

Step 4: Removal (Month 7+)

The feature is only removed in a major version bump (e.g., v2 → v3). The previous major version continues receiving critical patches for 12 months after the new major version launches. A migration guide is included prominently in the release notes.

Step 5: Previous Version Support (Months 7–19)

The v2.x version continues to receive critical security patches for this entire period. However, v2.x does not receive new features—only critical patches are applied. After 12 months, v2.x reaches end-of-life and no further patches are provided.

Example timeline shows the concrete dates: In 2025-01, v2.0 is released. In 2025-03, deprecation is announced for --old-flag. From 2025-04 through 2025-08, the 6-month deprecation period runs. In 2025-09, v3.0 is released and --old-flag is removed. From 2025-09 through 2026-09, v2.x receives critical patches only. In 2026-10, v2.x reaches end-of-life.

Security Update Commitments

CVE Fix SLAs

When a security vulnerability is discovered in CleanStart, response times depend on severity. Critical vulnerabilities (CVSS ≥ 9.0) trigger triage within 1 hour and have a patch available within 24 hours, typically the same or next business day. High severity vulnerabilities (CVSS 7.0–8.9) are triaged within 4 hours and patched within 7 days, ensuring resolution within one week. Medium severity vulnerabilities (CVSS 4.0–6.9) are triaged within 1 business day and patched within 30 days. Low severity vulnerabilities (CVSS < 4.0) are triaged within 3 business days and patched within 90 days.

Example: Thursday 10:00 UTC a critical CVE is published. Thursday 10:30 UTC, CleanStart triage completes. Friday 10:00 UTC, a patched image is published (within the 24-hour SLA). The patch is released as python:3.12.5 (a PATCH version bump).

Patch Delivery Channels

All security patches are available through multiple channels to ensure you can receive them promptly. The public registry at registry.cleanstart.com makes patches immediately available to all customers. Release notes are published publicly announcing new patches. An optional mailing list provides email notifications for security advisories. Critical and high-severity CVEs are also published via GHSA (GitHub Security Advisory) format for integration with security tools.

Previous Version Patch Support

The current version receives all patches, both security and bug fixes. The previous minor version receives critical security patches (with a 24-hour SLA). Older versions beyond the immediately previous minor version require commercial support agreements.

Example: If python:3.12 is the current version, it receives all patches. Python:3.11 receives critical patches only. Python:3.10 requires a paid support option.

Breaking Change Policy

What Constitutes a Breaking Change

Any change that requires code or configuration changes is a breaking change. This includes removed CLI flags that existing scripts depend on. Changed API endpoint behavior that alters the meaning of responses. Removed image tools or features that applications were using. Changed required parameters or changed parameter meanings. Removed language runtime functionality that applications relied on.

Breaking Change Rules

Breaking changes follow strict rules to protect users. They only happen in major version bumps (v2 → v3, never in v2.0 → v2.1). A 6-month minimum notice period is always provided before removal. A migration guide with step-by-step instructions is provided. The previous version is supported for 12 additional months with critical patches. Breaking changes are clearly documented prominently in release notes.

Examples of What IS a Breaking Change

v2.0: cleanimg-init --base-image python:3.12v3.0: cleanimg init --base python:3.12  # Subcommand renamed  ↑ BREAKING CHANGE, requires major bump

v1.0: GET /api/v1/images returns 200v1.1: GET /api/v1/images may include ?filter= parameterThis is a breaking change only if it changes required behavior. It is not a breaking change if ?filter= is optional.

Examples of What IS NOT a Breaking Change

v2.0: cleanimg-init --signature-type cosignv2.5: cleanimg-init --signature-type cosign,notary  ↑ NOT breaking (backward compatible, extended options)

v1.0: GET /api/v1/images returns {"id": "...", "version": "..."}v1.5: GET /api/v1/images returns {"id": "...", "version": "...", "sbom": {...}}  ↑ NOT breaking (old fields present, new fields added)

Notification of Changes

Release Notes

Every release is published at https://docs.clnstrt.dev/releases/. Each release note includes the date, version number, a list of all changes (grouped by category), and compatibility notes clearly stating which changes are breaking and what migration steps are required.

Email Notifications

Customers can opt-in for selective notifications at https://clnstrt.dev/subscribe. You can choose to receive security updates only, breaking changes only, or notifications for all releases. This allows you to stay informed at the level that's appropriate for your needs.

Security Advisories

Critical and high-severity CVEs are published via GHSA at https://github.com/cleanstart/images/security/advisories. These advisories are available to all customers and can be integrated with security tools and automated scanning systems.

Status Page

Real-time status and announcements are available at https://status.clnstrt.dev. The status page shows service health, ongoing incidents, and planned maintenance.

Support for Multiple Versions

Version Matrix

Patch Timeline Example

The patch timeline demonstrates how patches flow across versions. On 2025-01-15, a critical CVE is disclosed affecting glibc. On 2025-01-15, patches are released for all supported versions (python:3.x.x with patch, python:2.x.x with patch if v2 is still supported). On 2024-12-01, image v3.0 is released. On 2025-01-02, image v2.x reaches end of life (12 months after v3 launch). When the critical CVE is disclosed on 2025-01-15, patches are released for v3 only since v2 is EOL.

What This Means For You

For Deployment

If you pin to a specific version like python:3.12.1, you get a fixed, immutable image. PATCH updates are automatic as security patches are applied to the same tag. MINOR updates require a new tag and you decide when to update. MAJOR updates require a new tag, and you receive 6 months notice before the old version reaches end-of-life.

For CI/CD Integration

If you pin to a minor version like python:3.12, you get the latest 3.12.x automatically as patches are released. PATCH updates are automatic since the same tag moves to newer patches. MINOR updates require switching to a new tag like python:3.13. MAJOR updates require switching to a new tag like python:4.

For Long-Term Support

CleanStart supports the current major version indefinitely with patches. The previous major version is supported for 24 months with critical patches only. Older versions remain available but receive no support. Plan your upgrades so you upgrade to the latest major version every 24 months.

Feedback and Questions

Have concerns about this compatibility policy? Technical questions can be directed to support@clnstrt.dev. Policy feedback is welcome at policy@clnstrt.dev. Enterprise tier customers requesting exceptions to this policy can contact enterprise@clnstrt.dev.

What to Read Next

08-reference/quickstart/release-notes.md: Latest version changes and security updates. 08-reference/deployment/container-image-security.md: Verify image signatures and integrity. 06-operate/kubernetes-helm/canary-progressive-delivery.md: Safe rollout strategies for version upgrades.