Deprecation Policy

This policy defines how external interfaces are deprecated, maintained during a transition period, and eventually removed. It satisfies the OpenSSF Best Practices Silver badge criterion interfaces_deprecation, which requires projects to document deprecation announcement, maintenance duration, migration assistance, and breaking-change communication.

Scope

This policy applies to all external interfaces that users or downstream automation depend on:

Interface Type	Examples	Location
Shell script arguments	--config-dir, --tf-dir, --dry-run	infrastructure/setup/, scripts/
Environment variables	GPU_OPERATOR_VERSION, NS_GPU_OPERATOR	infrastructure/setup/defaults.conf
Terraform variables	environment, should_deploy_postgresql	infrastructure/terraform/variables.tf
Terraform outputs	aks_cluster, postgresql_connection_info	infrastructure/terraform/outputs.tf
Configuration schemas	Recording config properties	data-pipeline/capture/config/recording_config.schema.json
Workflow templates	AzureML and OSMO YAML fields	workflows/

Internal implementation details, private functions, and module-internal resources are excluded. Changes to these do not require a deprecation notice.

Deprecation Lifecycle

Every deprecation follows four stages:

1. Announce: Document the deprecation in the pull request that introduces the replacement. Include the rationale, replacement interface, and removal timeline.
2. Deprecation Period: Maintain the deprecated interface alongside its replacement for the defined period. Both interfaces function identically during this window.
3. Migrate: Provide migration guidance in the same pull request. Users follow the documented steps to transition from the deprecated interface to the replacement.
4. Remove: Remove the deprecated interface after the deprecation period expires. The removal commit references the original deprecation notice.

Deprecation Period

Deprecated interfaces are maintained for 90 calendar days or 1 version release containing breaking changes (whichever is longer).

NOTE

While the project is pre-1.0 with bump-minor-pre-major: true, breaking changes trigger minor version bumps (0.x.0). Post-1.0, the same commits trigger major bumps. The compound wording "1 version release containing breaking changes" is version-scheme-agnostic and applies correctly in both phases.

Announcement Channels

Each deprecation is communicated through all of the following channels:

Channel	Required Action
CHANGELOG.md	Add entry under a Deprecated section
Affected documentation	Add > [!WARNING] alert with deprecation timeline and replacement
GitHub Discussions	Post announcement in the Announcements category
GitHub Issues	Create tracking issue with deprecated label
PR description	Include migration steps and deprecation rationale

Migration Guidance

Every deprecation pull request includes:

• Description of what changed and why
• Replacement interface with usage example
• Step-by-step migration instructions
• Timeline for removal

Use this template for deprecation notices in documentation:

```markdown
> [!WARNING]
> **Deprecated**: `OLD_INTERFACE` is deprecated and will be removed in vX.Y.0 (estimated YYYY-MM-DD).
>
> **Replacement**: Use `NEW_INTERFACE` instead.
>
> **Migration**:
>
> 1. Replace `OLD_INTERFACE` with `NEW_INTERFACE` in your configuration.
> 2. Update any scripts referencing the old interface.
> 3. See [migration guide](link-to-guide) for details.
```

Breaking Change Communication

Breaking changes follow the decision tier defined in GOVERNANCE.md, which requires two maintainer approvals with explicit breaking-change acknowledgment and a documented migration path. The communication plan in Pull Request Process uses Conventional Commit breaking-change markers (! or a BREAKING CHANGE: footer) for release-please. Include migration guidance in release notes, updated deployment documentation, and an announcement in repository discussions.

No external interface will be removed without a deprecation notice in a prior release.

Example Deprecation Notice

The following hypothetical example renames OLD_COMPONENT_VERSION to NEW_COMPONENT_VERSION. These are illustrative names, not active repository variables or a current deprecation.

Documentation alert added to the affected guide:

> [!WARNING]
> **Deprecated**: `OLD_COMPONENT_VERSION` is deprecated and will be removed in vX.Y.0 (estimated YYYY-MM-DD).
>
> **Replacement**: Use `NEW_COMPONENT_VERSION` instead.
>
> **Migration**:
>
> 1. Replace `OLD_COMPONENT_VERSION` with `NEW_COMPONENT_VERSION` in `defaults.conf` and any `.env.local` overrides.
> 2. Update CI/CD pipelines or scripts that set this variable.
> 3. Both variable names are honored during the deprecation period; the old name takes lower precedence.

CHANGELOG.md entry:

### Deprecated

* `OLD_COMPONENT_VERSION` environment variable in `defaults.conf` is deprecated in favor of `NEW_COMPONENT_VERSION`. The old variable will be removed after 90 days or 1 breaking-change release (whichever is longer).

Migration steps:

1. Rename OLD_COMPONENT_VERSION to NEW_COMPONENT_VERSION in the affected configuration.
2. Search for OLD_COMPONENT_VERSION in any .env.local files or CI/CD variables and update them.
3. Verify the affected script's resolved configuration with --config-preview.

Active Deprecations

No interfaces are currently deprecated. When deprecations occur, they are listed here with replacement guidance and removal timelines.

Related Documentation

• GOVERNANCE.md — Decision tiers for breaking changes
• Documentation Maintenance — Deprecation notice formatting rules
• Pull Request Process — Breaking change communication channels
• Contribution Workflow — Enhancement submission requirements