Skip to content

Document how public APIs are obsoleted - #1117

Open
mauroservienti wants to merge 1 commit into
masterfrom
document-obsoleting-apis
Open

mauroservienti wants to merge 1 commit into
masterfrom
document-obsoleting-apis

Conversation

@mauroservienti

Copy link
Copy Markdown
Member

Adds an "Obsoleting public APIs" section to RELEASING.md, and a pointer to it in CLAUDE.md.

The policy:

  • A minor of major N: [Obsolete] with a warning. The API keeps working.
  • N+1.0.0: [Obsolete] with an error.
  • N+2.0.0: removed.

The obsolete message says what to use instead, and in which versions the API becomes an error and gets removed.

Because master builds the next major, obsoleting takes two pull requests: the error on master, and the warning as a backport to the release branch of the minor that ships it. That backport isn't a plain cherry-pick, since the attribute differs.

The section also covers the follow-up steps:

  • open a removal issue in the N+2.0.0 milestone;
  • mention the change in the release notes and the upgrade guide;
  • update the API approval file;
  • keep the tests covering the obsolete API, suppressing the warning locally with #pragma rather than a project-wide NoWarn.

The first use will be EnableCompositionOverControllers() (#1116).

Public APIs are obsoleted with a warning in a minor, become an error in
the next major, and are removed in the major after that. Since master
builds the next major, the error goes to master and the warning to the
release branch, through a separate backport.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant