---
title: Shared Compatibility Guidelines
owner: Product Spec Maintainers
status: draft
created: 2026-03-16
last_updated: 2026-03-16
---

# Shared Compatibility Guidelines

Feature specs should reference the relevant compatibility guidelines from this document and describe any unsupported combinations or explicit boundaries. Use feature-local text only when a capability introduces compatibility behavior that is narrower or more specific than these shared rules.

## How to Use

- Cite applicable `COMP-###` IDs in PRDs, architecture docs, and rollout guidance.
- Document unsupported version combinations explicitly rather than leaving behavior implied.
- Use these guidelines to shape upgrade, downgrade, and integration validation scenarios.

## COMP-001 Preserve Backward-Compatible Behavior by Default

Guideline:
New features should avoid breaking existing supported behavior, interfaces, or workflows for current users unless the change is explicitly versioned and communicated.

Rationale:
Infrastructure products accumulate automation and dependencies that are expensive to rewrite.

## COMP-002 Define Forward-Compatibility Boundaries

Guideline:
When forward compatibility is limited, the feature should state what newer-produced artifacts, metadata, or protocol behavior older components may reject or ignore.

Rationale:
Undefined forward-compatibility assumptions create rollback and skew risk.

## COMP-003 Support Rolling Upgrade Where Product Policy Allows

Guideline:
If the product supports rolling upgrades, new feature behavior should be safe under that model and should not require all components to switch versions simultaneously without explicit documentation.

Rationale:
Many production environments cannot tolerate full-stop upgrades.

## COMP-004 Mixed-Version Semantics Must Be Explicit

Guideline:
Temporary mixed-version operation must have documented expectations, including which component version controls behavior and which combinations are unsupported.

Rationale:
Version skew is normal during upgrade windows and must be predictable.

## COMP-005 Preserve Stable External APIs and Contracts

Guideline:
Public APIs, event contracts, configuration schemas, and user-visible status surfaces should remain stable across supported releases unless versioned changes are introduced.

Rationale:
External contracts drive automation, client integrations, and long-lived operational tooling.

## COMP-006 Protect Protocol Compatibility

Guideline:
Features that emit or consume wire protocols, message formats, or replication streams should define compatibility expectations with existing producers, consumers, and sinks.

Rationale:
Protocol mismatches often fail late and create cross-team incidents.

## COMP-007 Metadata Format Changes Need a Compatibility Story

Guideline:
Changes to persisted metadata, checkpoints, or state formats should include an explicit read/write compatibility model and recovery guidance.

Rationale:
Metadata incompatibility can block restart, rollback, or disaster recovery.

## COMP-008 Downgrade and Rollback Boundaries Must Be Clear

Guideline:
If a feature introduces an irreversible state transition, the rollback window and exact downgrade boundary must be documented before release.

Rationale:
Operators need to know when rollback remains safe and when it requires remediation.

## COMP-009 Handle Version Skew Deliberately

Guideline:
Controllers, agents, clients, and managed services that may run with version skew should define supported skew ranges and failure behavior outside those ranges.

Rationale:
Skew is common in large fleets and should not be treated as an edge case.

## COMP-010 Document Unsupported Combinations

Guideline:
Unsupported combinations of versions, topologies, deployment modes, or downstream integrations should be documented explicitly in the feature spec.

Rationale:
Clear exclusions prevent accidental production use based on optimistic assumptions.