Skip to content

Commit ca2328d

Browse files
TrottBridgeAR
authored andcommitted
doc: edit deprecation section of Collaborator Guide
Edit the last few paragraphs of the Collaborator Guide section on deprecations. PR-URL: #26419 Reviewed-By: Beth Griggs <Bethany.Griggs@uk.ibm.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent 05b92c9 commit ca2328d

File tree

1 file changed

+16
-15
lines changed

1 file changed

+16
-15
lines changed

COLLABORATOR_GUIDE.md

+16-15
Original file line numberDiff line numberDiff line change
@@ -334,7 +334,7 @@ documentation must state the deprecation status.
334334
* Emits a warning at runtime on first use of the deprecated API.
335335
* If used with the [`--throw-deprecation`][] flag, will throw a runtime error.
336336

337-
* End-of-life
337+
* End-of-Life
338338
* The API is no longer subject to the semantic versioning rules.
339339
* Backward-incompatible changes including complete removal of such APIs may
340340
occur at any time.
@@ -343,32 +343,33 @@ Apply the `notable change` label to all pull requests that introduce
343343
Documentation-Only Deprecations. Such deprecations have no impact on code
344344
execution. Thus, they are not breaking changes (`semver-major`).
345345

346-
Runtime Deprecations and End-of-life APIs (internal or public) are breaking
346+
Runtime Deprecations and End-of-Life APIs (internal or public) are breaking
347347
changes (`semver-major`). The TSC may make exceptions, deciding that one of
348348
these deprecations is not a breaking change.
349349

350350
All deprecations receive a unique and immutable identifier. Documentation,
351351
warnings, and errors use the identifier when referring to the deprecation. The
352-
documentation for the assigned deprecation identifier must always remain in the
353-
API documentation. This is true even if the deprecation is no longer in use (for
352+
documentation for the deprecation identifier must always remain in the API
353+
documentation. This is true even if the deprecation is no longer in use (for
354354
example, due to removal of an End-of-Life deprecated API).
355355

356356
<a id="deprecation-cycle"></a>
357-
A _Deprecation cycle_ is a major release during which an API has been in one of
357+
A _deprecation cycle_ is a major release during which an API has been in one of
358358
the three Deprecation levels. Documentation-Only Deprecations may land in a
359-
minor release but must not be upgraded to a Runtime Deprecation until the next
360-
major release.
359+
minor release. They may not change to a Runtime Deprecation until the next major
360+
release.
361361

362-
No API can be moved to End-of-life without first having gone through a
363-
Runtime Deprecation cycle. However, there is no requirement that deprecated
364-
code must progress ultimately to *End-of-Life*. Documentation-only and runtime
365-
deprecations may remain indefinitely.
362+
No API can change to End-of-life without going through a Runtime Deprecation
363+
cycle. There is no rule that deprecated code must progress to End-of-Life.
364+
Documentation-Only and Runtime Deprecations may remain in place for an unlimited
365+
duration.
366366

367367
Communicate pending deprecations and associated mitigations with the ecosystem
368-
as soon as possible (preferably before the pull request adding the deprecation
369-
lands on the master branch). Use the `notable-change` label on all pull requests
370-
that add a new deprecation or move an existing deprecation to a new deprecation
371-
level.
368+
as soon as possible. If possible, do it before the pull request adding the
369+
deprecation lands on the master branch.
370+
371+
Use the `notable-change` label on pull requests that add or change the
372+
deprecation level of an API.
372373

373374
### Involving the TSC
374375

0 commit comments

Comments
 (0)