Deprecation Policy (Formal)

This policy defines how g3nretailstack deprecates and sunsets public contract surfaces: API Gateway endpoints, MCP resources/tools, direct Lambda actions exposed to customers, and published OpenAPI/JSON Schemas.

Definitions

• Deprecation: the feature remains available but is scheduled for removal or breaking change.
• Sunset: the date after which the feature is removed or behavior changes in a breaking way.

Minimum notice windows

• Breaking changes to public endpoints/schemas: ≥ 90 days notice.
• Removal of endpoints/schemas: ≥ 180 days after notice.
• Behavioral changes that are not breaking (additive changes): document before or at release.
• Security emergencies: may shorten windows to protect tenants; communicate as soon as possible and document the rationale.

Required communications

Every deprecation must include all of the following:

1. Docs notice in the relevant service page (Surfaces + Calls) and in this policy page.
2. Response headers on the deprecated endpoint:
   • Deprecation: true (or an RFC3339 timestamp)
   • Sunset: <RFC3339 timestamp>
   • Link: <https://doc.g3nretailstack.com/common/deprecation-policy.html>; rel="deprecation"
   • Optional: x-g3n-deprecation: <short message>
3. Release notes in the service’s docs (changelog/notes section).

Schema requirements

• OpenAPI operations must set deprecated: true once deprecated.
• OpenAPI should include x-deprecation-notice, x-deprecation-sunset, and x-deprecation-replacement when applicable.
• JSON Schemas should include deprecated: true and a short x-deprecation notice (when the schema itself is deprecated).

Client expectations

• Clients must treat unknown fields as additive and safe to ignore.
• Clients must watch for deprecation headers and plan migration before sunset.
• SDKs must surface deprecation headers in logs or telemetry to prevent silent breakage.

Standard replacement posture

When a breaking change is required:

• Introduce a new endpoint (or new schema) instead of mutating the existing one.
• Keep the old endpoint active for at least the notice window.
• Provide a concrete migration guide with field-by-field mapping and examples.

Exceptions

Only security incidents that would materially impact tenant safety may bypass the notice windows. When this happens:

• Post a public notice in docs,
• Include the deprecation headers immediately,
• Document the emergency rationale and the safest migration path.