Minor freshness updates to versioning docs
PiperOrigin-RevId: 623940465
Change-Id: I3b0136b529b984675f0caa900c463f4d8005eb6d
diff --git a/docs/versioning.md b/docs/versioning.md
index 74dc68e..e427b13 100644
--- a/docs/versioning.md
+++ b/docs/versioning.md
@@ -62,6 +62,11 @@
Stable (no-suffix)
: Recommended for production use.
+In the past -- and only in rare cases -- libraries have used a `-devXX` suffix
+to indicate that a public release does not yet meet the requirements for Alpha.
+We **strongly discourage** libraries from using `-devXX`, as failing to meet the
+requirements for Alpha indicates that a library should not be publicly released.
+
### Major (`x.0.0`) {#major}
An artifact's major version indicates a guaranteed forward-compatibility window.
@@ -104,7 +109,7 @@
#### Process requirements {#major-process}
-If the artifact has dependencies within Jetpack, owners *must* complete the
+If the artifact has dependencies within Jetpack, owners *must* complete an
assessment before implementing any breaking changes to binary or behavioral
compatibility.
@@ -159,34 +164,33 @@
Snapshot releases are whatever exists at tip-of-tree. They are only subject to
the constraints placed on the average commit. Depending on when it's cut, a
-snapshot may even be binary-identical to an `alpha`, `beta`, or `stable`
-release.
+snapshot may even be binary-identical to an `alpha`, `beta`, or `RC` release.
### Tooling guarantees
Versioning policies are enforced by the following Gradle tasks:
-`checkApi`: ensures that changes to public API are intentional and tracked,
-asking the developer to explicitly run `updateApi` (see below) if any changes
-are detected
+- `checkApi`: ensures that changes to public API are intentional and tracked,
+ asking the developer to explicitly run `updateApi` (see below) if any
+ changes are detected
-`checkApiRelease`: verifies that API changes between previously released and
-currently under-development versions conform to semantic versioning guarantees
+- `checkApiRelease`: verifies that API changes between previously released and
+ currently under-development versions conform to semantic versioning
+ guarantees
-`updateApi`: commits API changes to source control in such a way that they can
-be reviewed in pre-submit via Gerrit API+1 and reviewed in post-submit by API
-Council
+- `updateApi`: commits API changes to source control in such a way that they
+ can be reviewed in pre-submit via Gerrit `API+2` and reviewed in post-submit
+ by API Council
-`SNAPSHOT`: is automatically added to the version string for all builds that
-occur outside the build server for release branches (ex. ub-androidx-release).
-Local release builds may be forced by passing -Prelease to the Gradle command
-line.
+`SNAPSHOT` is automatically added to the version string for all builds that
+occur outside the build server for release branches. Local release builds may be
+forced by passing `-Prelease` to the Gradle command line.
## Picking the right version {#picking-the-right-version}
-Libraries follow [semantic versioning](https://semver.org), which means that the
-version code is strongly tied to the API surface. A full version consists of
-revision numbers for major, minor, and bugfix as well as a pre-release stage and
+Libraries follow [semantic versioning](#semver), which means that the version
+code is strongly tied to the API surface. A full version consists of revision
+numbers for major, minor, and bugfix as well as a pre-release stage and
revision. Correct versioning is, for the most part, automatically enforced;
however, please check for the following:
@@ -218,11 +222,11 @@
period" gives developers time to try each version, find bugs, and ensure a
quality stable release. Therefore, at minimum:
-- An `alpha` version must be publically available for 2 weeks before releasing
- a public `beta`
-- A `beta` version must be publically available for 2 weeks before releasing
- an public `rc`
-- A `rc` version must be publically available for 2 weeks before releasing a
+- An `alpha` version must be publicly available for 2 weeks before releasing a
+ public `beta`
+- A `beta` version must be publicly available for 2 weeks before releasing a
+ public `rc`
+- A `rc` version must be publicly available for 2 weeks before releasing a
public stable version
Your library must meet the following criteria to move your public release to
@@ -270,7 +274,8 @@
any changes likely to introduce additional functional instability. Requests for
exceptions **must** be accompanied by a justification explaining why the change
cannot be made in a future minor version. This policy does not apply to
-additions of `@Experimental` APIs or changes to `@Experimental` APIs.
+additions of experimental `@RequiresOptIn` APIs or changes to `@RequiresOptIn`
+APIs.
#### Checklist for moving to `beta01` {#beta-checklist}
@@ -353,13 +358,12 @@
A few notes about version updates:
- The version of your library listed in `androidx-main` should *always* be
- higher than the version publically available on Google Maven. This allows us
+ higher than the version publicly available on Google Maven. This allows us
to do proper version tracking and API tracking.
- Version increments must be done before the CL cutoff date (aka the build cut
date).
- **Increments to the next stability suffix** (like `alpha` to `beta`) should
- be handled by the library owner, with the Jetpack TPM (natnaelbelay@) CC'd
- for API+1.
+ be handled by the library owner
- Version increments in release branches will need to follow the guide
[How to update your version on a release branch](/docs/release_branches.md#update-your-version)
- When you're ready for `rc01`, the increment to `rc01` should be done in
@@ -372,7 +376,7 @@
### How to update your version
-1. Update the version listed in `frameworks/support/libraryversions.toml`
+1. Update the version listed in `libraryversions.toml`
1. If your library is a `beta` or `rc01` version, run `./gradlew
<your-lib>:updateApi`. This will create an API txt file for the new version
of your library. For other versions, this step is not required
