Skip to content

Commit a6ed61f

Browse files
committed
doc: add experimental modules review policy
Signed-off-by: Paolo Insogna <paolo@cowtech.it>
1 parent ed05549 commit a6ed61f

File tree

3 files changed

+42
-0
lines changed

3 files changed

+42
-0
lines changed

doc/api/documentation.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,16 @@ The stability indexes are as follows:
4747
>
4848
> Experimental features leave the experimental status typically either by
4949
> graduating to stable, or are removed without a deprecation cycle.
50+
>
51+
> As part of the major-release experimental module review process,
52+
> collaborators who introduce experimental modules are expected to take
53+
> ownership and help bring each experiment to a conclusion: either promotion
54+
> to stable or removal.
55+
>
56+
> If an experimental feature has reached mainstream adoption such that breaking
57+
> changes are not realistically possible without ecosystem breakage, it should
58+
> be considered stable in the next experimental module review issue, regardless
59+
> of development status or author intent.
5060
5161
<!-- separator -->
5262

doc/contributing/collaborator-guide.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -462,6 +462,9 @@ For pull requests introducing new core modules:
462462
* Land only after sign-off from at least two TSC voting members.
463463
* Land with a [Stability Index][] of Experimental. The module must remain
464464
Experimental until a semver-major release.
465+
* Introducing an Experimental module means taking ownership of the experiment
466+
and participating in the major-release experimental module review process
467+
until the module is either promoted to Stable or removed.
465468

466469
### Introducing new APIs on the global scope
467470

doc/contributing/releases.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1283,6 +1283,35 @@ The release date for the next major release should be announced immediately
12831283
following the current release (e.g. the release date for 13.0.0 should be
12841284
announced immediately following the release of 12.0.0).
12851285

1286+
### Experimental module review
1287+
1288+
Approximately one month before cutting a new major release, releasers must
1289+
open an issue asking collaborators involved with experimental modules to review
1290+
their status and propose updates.
1291+
1292+
Releasers are not required to make module-status decisions themselves.
1293+
1294+
That issue should include an explicit list of all experimental modules, and
1295+
should also explicitly mention a collaborator for each module when possible.
1296+
1297+
The discussion should identify:
1298+
1299+
* Modules that should be promoted to stable.
1300+
* Modules that should have their experimental stage changed.
1301+
* Modules that should be removed from the codebase.
1302+
1303+
The issue is for discussion only and should not itself be turned into a pull
1304+
request. Once decisions are made, the issue must be closed.
1305+
1306+
The final comment before closing should summarize, for each module:
1307+
1308+
1. Whether a change will be made.
1309+
2. The reason for the change, or the reason for no change.
1310+
3. An implementing pull request, if one exists.
1311+
1312+
The issue should link the same purpose issue created for the previous major release
1313+
so that modules status comparison is simplified.
1314+
12861315
### Release branch
12871316

12881317
Approximately two months before a major release, new `vN.x` and

0 commit comments

Comments
 (0)