Lots of minor freshness updates to high-traffic pages
PiperOrigin-RevId: 595171199
Change-Id: I31f9123239082c6bb8ba8ad23159393553b63621
diff --git a/docs/api_guidelines/dependencies.md b/docs/api_guidelines/dependencies.md
index b1f3454..770ad70 100644
--- a/docs/api_guidelines/dependencies.md
+++ b/docs/api_guidelines/dependencies.md
@@ -8,14 +8,17 @@
### Versioned artifacts {#dependencies-versioned}
One of the most difficult aspects of independently-versioned releases is
-maintaining compatibility with public artifacts. In a mono repo such as Google's
-repository or Android Git at `master` revision, it's easy for an artifact to
+maintaining compatibility with public artifacts. In a monorepo such as Google's
+repository or Android Git at `main` revision, it's easy for an artifact to
accidentally gain a dependency on a feature that may not be released on the same
schedule.
+To address this problem, library owners in AndroidX can choose from several
+types of dependencies:
+
- Project `project(":core:core")` uses the tip-of-tree sources for the
`androidx.core:core` library and requires that they be loaded in the
- workspace.
+ workspace and released at the same time.
- Playground `projectOrArtifact(":core:core")` is used for the
[Playground](/docs/playground.md) workflow and will use
tip-of-tree sources, if present in the workspace, or `SNAPSHOT` prebuilt
@@ -29,7 +32,8 @@
project or Playground specs in cases where tip-of-tree APIs or behaviors are
required.
-**Do not** change a dependency version to increase adoption.
+**Do not** upgrade the version of a library's dependency to artificially boost
+adoption of that version.
#### Pre-release dependencies {#dependencies-pre-release}
@@ -43,10 +47,9 @@
#### Pinned versions {#dependencies-prebuilt}
To avoid issues with dependency versioning, pin your dependencies to the oldest
-stable version of an artifact (available via local `maven_repo` or Google Maven)
-that includes the necessary APIs. This will ensure that the artifact's release
-schedule is not accidentally tied to that of another artifact and will allow
-developers to use older libraries if desired.
+stable version of an artifact that includes the necessary APIs. This will ensure
+that the artifact's release schedule is not accidentally tied to that of another
+artifact and will allow developers to use older libraries if desired.
```
dependencies {
@@ -80,18 +83,17 @@
[`@RestrictTo` APIs](/docs/api_guidelines#restricted-api) for
more details.
-NOTE Dependency versioning policies are enforced at build time in the
-`createArchive` task, which ensures that pre-release version suffixes are
-propagated appropriately. Cross-artifact API usage policies are enforced by the
-`checkApi` and `checkApiRelease` tasks.
+Dependency versioning policies are enforced at build time in the `createArchive`
+task, which ensures that pre-release version suffixes are propagated
+appropriately. Cross-artifact API usage policies are enforced by the `checkApi`
+and `checkApiRelease` tasks.
### Third-party libraries {#dependencies-3p}
Artifacts may depend on libraries developed outside of AndroidX; however, they
must conform to the following guidelines:
-* Prebuilt **must** be checked into Android Git with both Maven and Make
- artifacts
+* Prebuilt **must** be checked into Android Git
* `prebuilts/maven_repo` is recommended if this dependency is only
intended for use with AndroidX artifacts, otherwise please use
`external`
diff --git a/docs/onboarding.md b/docs/onboarding.md
index 46b6e88..f4e5efa 100644
--- a/docs/onboarding.md
+++ b/docs/onboarding.md
@@ -7,10 +7,9 @@
This page does **not** cover best practices for the content of changes. Please
see [Life of a Jetpack Feature](/docs/loaf.md) for details on
-developing and releasing a library,
+creating and releasing a library or
[API Guidelines](/docs/api_guidelines/index.md) for best
-practices regarding public APIs and an overview of the constraints placed on
-changes.
+practices regarding library development.
## Workstation setup {#setup}
@@ -475,7 +474,7 @@
NOTE `./gradlew tasks` always has the canonical task information! When in doubt,
run `./gradlew tasks`
-#### Generate Docs
+#### Generate docs
To build API reference docs for both Java and Kotlin source code using Dackka,
run the Gradle task:
@@ -1070,6 +1069,6 @@
as well as `androidTestImplementation(libs.multidex)` to the dependenices block.
-If you want it enabled for the application and not test apk, add
+If you want it enabled for the application and not test APK, add
`implementation(libs.multidex)` to the dependencies block instead. Any prior
failures may not re-occur now that the software is multi-dexed. Rerun the build.
diff --git a/docs/versioning.md b/docs/versioning.md
index a63e3c0..74dc68e 100644
--- a/docs/versioning.md
+++ b/docs/versioning.md
@@ -408,8 +408,14 @@
### Can alpha work (ex. for the next Minor release) occur in the primary development branch during beta API lockdown?
-No. This is by design. Focus should be spent on improving the Beta version and
-adding documentation/samples/blog posts for usage!
+Generally, no. This is by design. Focus should be spent on improving the Beta
+version and adding documentation/samples/blog posts for usage!
+
+In limited cases, the
+[`@RequiresOptIn`](/docs/api_guidelines/index.md#experimental-api)
+meta-annotation may be used to extend development of a feature beyond the alpha
+cycle. When doing so, extreme care must be taken to avoid destabilizing the rest
+of the library.
### Is there an API freeze window between alpha and beta while API surface is reviewed and tests are added, but before the beta is released?
