Self-hosted Release/Support Matrix

A newer version is not the same as a supportable deployment

A self-hosted customer runs product 3.4.2; release 3.6.0 exists. The larger number invites “just upgrade,” but the tested matrix covers specific runtime/database combinations and no direct 3.4.x -> 3.6.x upgrade has been proven. A required schema migration also landed in 3.5.x. Semantic Versioning explains version meaning relative to a public API; it does not certify this customer's stack, migration path, rollback, or support window.

This lesson builds Self-hosted Release, Compatibility, Upgrade & Support Matrix v1 so release identity, deployment fingerprint, tested compatibility, upgrade hops, migration/backup/rollback, patch eligibility and EOL can reconstruct a bounded SUPPORTED / REVIEW / UNSUPPORTED decision.

Lesson boundary and route

AGN-014 owns the release/support matrix. AGN-013 owns subscription/grace/dunning and AGN-015 owns demand-gated multi-tenancy; those outcomes remain separate. AGN-012 is a hard prerequisite and AGN-013 a soft prerequisite.

Start with the current deployment fingerprint, then separate target release and version semantics, test runtime/database/schema against the matrix, evaluate upgrade hops, close migration/backup/rollback prerequisites, and only then determine support tier, patch eligibility, support end and EOL.

Mental model: four independent contracts

Treat a self-hosted support promise as four contracts: Release Semantics, Compatibility Evidence, Upgrade/Migration Path, and Support Window. Collapsing them into one version string destroys auditability.

SemVer 2.0.0 defines MAJOR for incompatible public-API changes, MINOR for backward-compatible functionality, and PATCH for backward-compatible bug fixes. It does not promise compatibility with every database or runtime. Kubernetes demonstrates the separation more concretely by publishing version-skew limits, upgrade order, and maintained release/support windows separately. MAKNOW therefore treats version ordering as never sufficient compatibility evidence.

Matrix foundation fields

Release identity starts with release_id, product_version, release_channel, public_api_version, and target release. Installation identity uses deployment_fingerprint, runtime_version, database_version, schema_version, os_or_container_ref, and dependency version.

Compatibility must bind to tested_runtime_versions, tested_database_versions, tested_matrix_id, and compatibility_evidence_ref. Upgrade evidence is separate: upgrade_from_version, upgrade_to_version, supported_upgrade_from_versions, upgrade_hop_state, migration_required, backup_required, and rollback_supported. Support policy then uses support_tier, patch_eligible, support_end, eol_state, and security_fix_policy_ref.

Why SemVer, compatibility and support are different

Keep three questions distinct: “what does this version label communicate?”, “was this deployment combination actually tested?”, and “until when does the vendor support which actions?” A 3.4.2 -> 3.6.0 path can look orderly while the direct hop remains unsupported. The runtime can be tested while a newer database minor is not. A technically compatible combination can still be outside the support window.

The evaluator therefore binds the fingerprint to a tested matrix first, then checks upgrade hops and migration prerequisites, and only then closes support tier/patch eligibility. Missing decisive evidence cannot be coerced into a positive state.

Baseline: an intermediate hop is mandatory

Installation A runs 3.4.2, runtime 8.0.8, database 14.9, schema 42. Target 3.6.0 tests that runtime/database family, but direct upgrades from 3.4.x are not supported. The path is 3.4.2 -> 3.5.4 -> 3.6.0, with a recorded migration at the intermediate hop. Backup evidence and a rollback plan are present.

The bounded result is not “install latest.” It is SUPPORTED_UPGRADE_WITH_INTERMEDIATE_HOP, yielding UPGRADE_PATH_REVIEW_READY only because the tested matrix, hop, migration, backup and rollback evidence all close.

Mutation: change the database to 15.1 but leave compatibility labeled TESTED_SUPPORTED. If 15.1 is absent from tested_database_versions, the evaluator must return HOLD_DATABASE_VERSION_UNTESTED; the label has no authority without evidence.

Important failure modes

1. Latest = compatible: version precedence is not a compatibility test.
2. PATCH = safe everywhere: patch semantics still depend on deployment compatibility.
3. Upgrade arithmetic: skipping 3.5 can skip a required migration.
4. Migration without backup: recovery evidence is incomplete.
5. rollback_supported=true without a ref: an assertion without evidence.
6. Support tier without support_end: time-bounded entitlement is not auditable.
7. EOL with patch_eligible=true: a policy conflict unless a traceable exception exists.
8. A vague compatibility range: a written range without a tested matrix is insufficient authority.

Upgrade, stay, or patch-only

UPGRADE is appropriate when the target combination is tested and the full path is closed. STAY can be the right answer when the current release remains supported and upgrade prerequisites are incomplete. PATCH_ONLY for a security fix without a feature upgrade is valid only when the release/tier is patch-eligible and the deployment combination stays inside the support boundary.

The lesson does not define “upgrade performed” as success. Success is a bounded, reproducible support decision. HOLD or STAY is often safer than an evidence-free upgrade.

Experienced bridge: make the matrix executable

If you already know SemVer and release pipelines, focus on consistency rules. Each release should expose a machine-readable matrix row. The evaluator should detect small mutations: a database minor changes, support_end passes, an upgrade hop disappears, a migration ref is removed, or rollback remains asserted without evidence.

Crucially, compatibility_state=TESTED_SUPPORTED cannot be a free-form label; it must match exact tested versions and evidence. Otherwise the matrix itself creates false confidence.

Guided and independent practice

Run the baseline and explain why the direct hop is rejected while the intermediate path is review-ready. Then switch the database to an untested version while leaving the compatibility label positive. Independently remove migration or backup evidence and identify the blocker.

For transfer, use a second containerized installation with a supported runtime, a newer untested database minor, and a security-patch-only request. Do not copy the baseline result; recompute patch eligibility from support tier plus deployment compatibility.

What must be reconstructable?

A reviewer must be able to identify current and target releases, the exact deployment fingerprint, which tested matrix covers runtime/database/schema, whether the path is direct or intermediate, migration/backup/rollback references, support tier and support end, patch policy, known incompatibilities, operator acknowledgement, and audit reference.

If any decisive answer reduces to “because the version is newer,” evidence is insufficient.

Assessment and transfer

The transfer deliberately separates patch semantics from compatibility: runtime is supported and the request is security-only, but the newer database minor has not been tested. The evaluator must not infer patch eligibility from version ordering; it should return HOLD_PATCH_ON_UNTESTED_DATABASE until compatibility evidence exists.

If later evidence adds that database minor to the tested matrix while the support tier still covers security fixes, the same fixture can recompute to PATCH_REVIEW_READY. Evidence change, not baseline-oracle reuse, should change the decision.

Fact / Inference / Design and freshness

FACT: SemVer 2.0.0 defines MAJOR/MINOR/PATCH relative to a public API. FACT: Kubernetes separately publishes version-skew limits, upgrade order, and maintained release/support windows. INFERENCE: separating release semantics, tested compatibility, upgrade path and support window improves auditability. DESIGN: support tiers, compatibility ranges, patch eligibility, migration policy and EOL policy remain MAKNOW/product-owner authority.

SemVer is foundational/stable. Kubernetes support policy is practice-evolving and must be rechecked by 2027-01-01 or earlier on material change. Neither source automatically defines MAKNOW policy.