docs: Add deprecation policy by scouten-adobe · Pull Request #2148 · contentauth/c2pa-rs

scouten-adobe · 2026-05-13T22:28:29Z

No description provided.

codecov · 2026-05-13T22:35:06Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.43%. Comparing base (d55fb2a) to head (45df7e0).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2148   +/-   ##
=======================================
  Coverage   78.43%   78.43%           
=======================================
  Files         177      177           
  Lines       45404    45404           
=======================================
  Hits        35614    35614           
  Misses       9790     9790

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

codspeed-hq · 2026-05-13T22:36:02Z

Merging this PR will not alter performance

✅ 30 untouched benchmarks
⏩ 64 skipped benchmarks¹

_{Comparing doc/deprecation-policy (45df7e0) with main (d55fb2a)}

64 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

crandmck

Mostly minor suggestions.

Please review punctuation of all list items to ensure they follow our style guide: Don’t end each bulleted item with a period unless it is a complete sentence, even if it completes a sentence begun in the introduction. (Claude can help with this.)

crandmck · 2026-05-14T16:26:54Z

+
+The Content Authenticity Initiative SDKs are evolving projects. Prior to their 1.0 release, the APIs may change as we refine our design. That said, we are committed to making those changes in a transparent, predictable way so that developers can plan accordingly.
+
+This policy applies to the Rust SDK and all language bindings (JavaScript, Node.js, C, C++, Swift, Kotlin, and Python).


Suggested change

This policy applies to the Rust SDK and all language bindings (JavaScript, Node.js, C, C++, Swift, Kotlin, and Python).

This policy applies to the Rust library and all language bindings (JavaScript, Node.js, C, C++, Swift, Kotlin, and Python).

Prefer to refer to each repo as a "library" vs. the entire set as the "SDK". This is the terminology used in the docs.

crandmck · 2026-05-14T16:34:01Z

+
+## Versioning and stability guarantees
+
+We follow [Semantic Versioning (SemVer)](https://semver.org/). Version 1.0.0 will define the public API, and after that release, the way version numbers are incremented will be dependent on how the public API changes: patch for backward-compatible bug fixes, minor for backward-compatible additions, and major for incompatible changes.


Suggested change

We follow [Semantic Versioning (SemVer)](https://semver.org/). Version 1.0.0 will define the public API, and after that release, the way version numbers are incremented will be dependent on how the public API changes: patch for backward-compatible bug fixes, minor for backward-compatible additions, and major for incompatible changes.

We follow [Semantic Versioning (SemVer)](https://semver.org/). Version 1.0.0 defines the public API, and subsequent version numbers are based on how the public API changes in the release:

- **Patch** release for backward-compatible bug fixes.

- **Minor** release for backward-compatible additions.

- **Major** release for incompatible changes.

Small wording change so that the doc will not be time-specific: "1.0.0 will define..." implies the release is in future--which it is now, but won't be later. And formatting change to make it easier to read.

crandmck · 2026-05-14T16:35:16Z

@@ -0,0 +1,139 @@
+# Deprecation policy
+
+## Preamble


Suggested change

## Preamble

No section heading is needed for this introductory section. "Preamble" is a bit grandiose for this document IMHO.

crandmck · 2026-05-14T16:37:48Z

+
+**Before 1.0:** Major version zero (`0.y.z`) is for initial development — anything may change at any time, and the public API should not be considered stable. In the Rust/Cargo ecosystem, this means that a change from `0.2.3` to `0.3.0` may include incompatible API changes. We will, however, make a good-faith effort to follow the deprecation process below even before 1.0, so that users have advance warning before breakage occurs.
+
+**After 1.0:** Breaking changes will only ship in major version bumps. Before completely removing functionality in a new major release, there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API. We will publish and retain historical documentation for at least each minor point release.


Suggested change

**After 1.0:** Breaking changes will only ship in major version bumps. Before completely removing functionality in a new major release, there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API. We will publish and retain historical documentation for at least each minor point release.

**After 1.0:** Breaking changes will only ship in major version increments. Before completely removing functionality in a new major release, there will be at least one minor release that contains the deprecation so that API consumers can smoothly transition to the new API. We will publish and retain historical documentation for at least each minor point release.

Small wording changes:

"should" -> "will" (assumig that this will always be true. If not, then we should specify exceptions)

"users" -> "API consumers" to clarify that we are not talking about end-users.

crandmck · 2026-05-14T16:40:51Z

+
+## What counts as a breaking change
+
+Not all changes are equal. Breaking changes are assumed to be major changes, but not all breaking changes are major. The goal is that the same code should be able to run against different minor revisions, and minor changes should require at most a few local annotations. (This document is Rust-specific; we will treat other languages as closely to this list as is feasible.)


This is confusing. Do you mean "Breaking changes are assumed to be major changes, but not all major changes are breaking changes." ?

If so, maybe reword as "All breaking changes are major changes, but not all major changes are breaking."

If not, then what exactly does this mean? Most breaking changes are major, but in some cases they are not? When are breaking changes NOT major??

Please clarify.

crandmck · 2026-05-14T16:46:29Z

+- Breaking changes to upstream or third-party libraries to the extent that those APIs are re-published by our library and thus break our own API compatibility
+- Any other change flagged by `cargo-server-checks` (or an equivalent tool for any other language) as breaking compatibility
+
+Changes we consider **non-breaking** (minor or patch):


Suggested change

Changes we consider **non-breaking** (minor or patch):

Non-breaking changes that require a minor or patch version change:

crandmck · 2026-05-14T16:49:15Z

+
+### Stage 2: Grace period
+
+The grace period is a timeframe during which the deprecated API remains operational before being retired. Our minimums are:


Suggested change

The grace period is a timeframe during which the deprecated API remains operational before being retired. Our minimums are:

During the grace period, the deprecated API remains operational before being retired. The _minimum_ grace periods are shown here.

crandmck · 2026-05-14T16:50:52Z

+
+### Stage 1: Deprecation notice (minor release)
+
+- The item is marked deprecated in source code using the appropriate language mechanism. (See "Language-specific deprecation annotations" below.)


This should be a numbered list, because the steps are performed in the specified order.

crandmck · 2026-05-14T16:54:06Z

+
+When we decide to remove or replace part of the public API, we follow a three-stage process:
+
+### Stage 1: Deprecation notice (minor release)


Suggested change

### Stage 1: Deprecation notice (minor release)

### Stage 1: Deprecation notice (minor release)

The initial stage provides advance notice of the deprecation:

crandmck · 2026-05-14T16:55:09Z

+
+During the grace period, the deprecated API will continue to work without functional regression. **Exception:** We may remove deprecated APIs before this window expires if needed to address serious security issues or vulnerabilities.
+
+### Stage 3: Removal


Suggested change

### Stage 3: Removal

### Stage 3: Removal

In the final stage, the item is actually removed from the API:

gpeacock

I left some comments in code about issues I found.

gpeacock · 2026-05-19T04:24:13Z

+### Rust
+
+```rust
+#[deprecated(since = "0.5.0", note = "Use `Builder::new_v2()` instead. Will be removed in 0.7.0.")]


There's no way we are going to know what version will remove the code. Versions are not fixed to a timeline. It's hard enough to estimate the version we deprecate given the way our builds go.

gpeacock · 2026-05-19T04:24:44Z

+### Stage 1: Deprecation notice (minor release)
+
+- The item is marked deprecated in source code using the appropriate language mechanism. (See "Language-specific deprecation annotations" below.)
+- The deprecation message includes: what is deprecated, why, what to use instead, and the earliest planned removal timeline. (See stage 2.)


I don't think it is practical or necessary to add the earliest removal timeline. that's very subjective. Stage 2 already lets people know our general rules. I think this would just be misleading most of the time.

gpeacock · 2026-05-19T04:29:17Z

+
+## Migration guides
+
+Every deprecation will be accompanied by a migration guide. We will provide alternatives or newer versions for deprecated features — if an item is scheduled for removal, users should know the recommended replacement.


I agree with the principal of letting people know that something is being removed and why. We should also let them know about alternatives. But the idea that every deprecation requires a before/after code comparison seems too much. Some should have this treatment, but not all. We have a LOT to deprecate. For some things no one ever knew about them and there were no previous code examples.

docs: Add deprecation policy

18e01db

scouten-adobe self-assigned this May 13, 2026

scouten-adobe added 2 commits May 13, 2026 15:37

Lost in translation …

0221b67

Remove reference to Python warning decorator

45df7e0

crandmck requested changes May 14, 2026

View reviewed changes

gpeacock requested changes May 19, 2026

View reviewed changes


		The Content Authenticity Initiative SDKs are evolving projects. Prior to their 1.0 release, the APIs may change as we refine our design. That said, we are committed to making those changes in a transparent, predictable way so that developers can plan accordingly.

		This policy applies to the Rust SDK and all language bindings (JavaScript, Node.js, C, C++, Swift, Kotlin, and Python).

	This policy applies to the Rust SDK and all language bindings (JavaScript, Node.js, C, C++, Swift, Kotlin, and Python).
	This policy applies to the Rust library and all language bindings (JavaScript, Node.js, C, C++, Swift, Kotlin, and Python).


		## Versioning and stability guarantees

		We follow [Semantic Versioning (SemVer)](https://semver.org/). Version 1.0.0 will define the public API, and after that release, the way version numbers are incremented will be dependent on how the public API changes: patch for backward-compatible bug fixes, minor for backward-compatible additions, and major for incompatible changes.

-We follow [Semantic Versioning (SemVer)](https://semver.org/). Version 1.0.0 will define the public API, and after that release, the way version numbers are incremented will be dependent on how the public API changes: patch for backward-compatible bug fixes, minor for backward-compatible additions, and major for incompatible changes.
+We follow [Semantic Versioning (SemVer)](https://semver.org/). Version 1.0.0 defines the public API, and subsequent version numbers are based on how the public API changes in the release:
+- **Patch** release for backward-compatible bug fixes.
+- **Minor** release for backward-compatible additions.
+- **Major** release for incompatible changes.


		Before 1.0: Major version zero (`0.y.z`) is for initial development — anything may change at any time, and the public API should not be considered stable. In the Rust/Cargo ecosystem, this means that a change from `0.2.3` to `0.3.0` may include incompatible API changes. We will, however, make a good-faith effort to follow the deprecation process below even before 1.0, so that users have advance warning before breakage occurs.

		After 1.0: Breaking changes will only ship in major version bumps. Before completely removing functionality in a new major release, there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API. We will publish and retain historical documentation for at least each minor point release.


		## What counts as a breaking change

		Not all changes are equal. Breaking changes are assumed to be major changes, but not all breaking changes are major. The goal is that the same code should be able to run against different minor revisions, and minor changes should require at most a few local annotations. (This document is Rust-specific; we will treat other languages as closely to this list as is feasible.)

	Changes we consider non-breaking (minor or patch):
	Non-breaking changes that require a minor or patch version change:


		### Stage 2: Grace period

		The grace period is a timeframe during which the deprecated API remains operational before being retired. Our minimums are:

	The grace period is a timeframe during which the deprecated API remains operational before being retired. Our minimums are:
	During the grace period, the deprecated API remains operational before being retired. The _minimum_ grace periods are shown here.


		### Stage 1: Deprecation notice (minor release)

		- The item is marked deprecated in source code using the appropriate language mechanism. (See "Language-specific deprecation annotations" below.)


		When we decide to remove or replace part of the public API, we follow a three-stage process:

		### Stage 1: Deprecation notice (minor release)


		During the grace period, the deprecated API will continue to work without functional regression. Exception: We may remove deprecated APIs before this window expires if needed to address serious security issues or vulnerabilities.

		### Stage 3: Removal


		## Migration guides

		Every deprecation will be accompanied by a migration guide. We will provide alternatives or newer versions for deprecated features — if an item is scheduled for removal, users should know the recommended replacement.

Conversation

scouten-adobe commented May 13, 2026

Uh oh!

codecov Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codspeed-hq Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

crandmck left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gpeacock left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov Bot commented May 13, 2026 •

edited

Loading

codspeed-hq Bot commented May 13, 2026 •

edited

Loading