Project import generated by Copybara.
PiperOrigin-RevId: 501845008
Change-Id: If3ae072b5c1be7efcef59be60c7cc3a99fbc87de
diff --git a/docs/api_guidelines/compat.md b/docs/api_guidelines/compat.md
index 3b2a251..cbc7bc8 100644
--- a/docs/api_guidelines/compat.md
+++ b/docs/api_guidelines/compat.md
@@ -245,22 +245,52 @@
}
```
-### Inter-process communication {#inter-process-communication}
+### Inter-process communication {#ipc}
Protocols and data structures used for IPC must support interoperability between
-different versions of libraries and should be treated similarly to public API.
+different versions of libraries and should be treated similarly to public API;
+however, AndroidX does not currently implement compatibility tracking for IPC.
-#### Data structures
+We recommend the following, in order of preference:
-**Do not** use `Parcelable` for any class that may be used for IPC or otherwise
-exposed as public API. The wire format used by `Parcelable` does not provide any
-compatibility guarantees and will result in crashes if fields are added or
-removed between library versions.
+1. Stable AIDL if (1) your project lives partially in the Android platform and
+ has access to Stable AIDL build rules and (2) you need to support Android's
+ `Parcelable` data types. The AndroidX workflow **does not** provide Stable
+ AIDL compilation or compatibility checks, so these would need to happen in
+ the platform build and the resulting `.java` files would need to be copied
+ out.
+2. Protobuf if (1) your project needs to persist data to disk or (2) you need
+ interoperability with systems already using Protobuf. Similar to Stable
+ AIDL, the AndroidX workflow **does not** provide built-in support Protobuf
+ compilation or compatibility checks. It is possible to use a Proto plug-in,
+ but you will be responsible for bundling the runtime and maintaining
+ compatibility on your own.
+3. Bundle if you have a very simple data model that is unlikely to change in
+ the future. Bundle has the weakest type safety and compatibility guarantees
+ of any recommendation, and it has many caveats that make it a poor choice.
+4. `VersionedParcelable` if your project is already using Versioned Parcelable
+ and is aware of its compatibility constraints.
**Do not** design your own serialization mechanism or wire format for disk
storage or inter-process communication. Preserving and verifying compatibility
is difficult and error-prone.
+In all cases, **do not** expose your serialization mechanism in your API
+surface. Neither Stable AIDL nor Protobuf generate stable language APIs.
+
+#### Parcelable {#ipc-parcelable}
+
+**Do not** implement `Parcelable` for any class that may be used for IPC or
+otherwise exposed as public API. By default, `Parcelable` does not provide any
+compatibility guarantees and will result in crashes if fields are added or
+removed between library versions. If you are using Stable AIDL, you *may* use
+AIDL-defined parcelables for IPC but not public API.
+
+NOTE As of 2022/12/16, we are working on experimental support for compiling and
+tracking Stable AIDL definitions within the AndroidX workflow.
+
+#### Protobuf {#ipc-protobuf}
+
Developers **should** use protocol buffers for most cases. See
[Protobuf](#dependencies-protobuf) for more information on using protocol
buffers in your library. **Do** use protocol buffers if your data structure is
@@ -268,6 +298,14 @@
`Binder`s, or other platform-defined `Parcelable` data structures, they will
need to be stored alongside the protobuf bytes in a `Bundle`.
+NOTE We are currently investigating the suitability of Square's
+[`wire` library](https://github.com/square/wire) for handling protocol buffers
+in Android libraries. If adopted, it will replace `proto` library dependencies.
+Libraries that expose their serialization mechanism in their API surface *will
+not be able to migrate*.
+
+#### Bundle {#ipc-bundle}
+
Developers **may** use `Bundle` in simple cases that require sending `Binder`s,
`FileDescriptor`s, or platform `Parcelable`s across IPC
([example](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:core/core/src/main/java/androidx/core/graphics/drawable/IconCompat.java;l=820)).
@@ -290,19 +328,7 @@
are responsible for providing their own system for guaranteeing wire format
compatibility between versions.
-Developers **may** use `VersionedParcelable` in cases where they are already
-using the library and understand its limitations.
-
-In all cases, **do not** expose your serialization mechanism in your API
-surface.
-
-NOTE We are currently investigating the suitability of Square's
-[`wire` library](https://github.com/square/wire) for handling protocol buffers
-in Android libraries. If adopted, it will replace `proto` library dependencies.
-Libraries that expose their serialization mechanism in their API surface *will
-not be able to migrate*.
-
-#### Communication protocols
+#### Communication protocols {#ipc-protocol}
Any communication prototcol, handshake, etc. must maintain compatibility
consistent with SemVer guidelines. Consider how your protocol will handle
diff --git a/docs/api_guidelines/dependencies.md b/docs/api_guidelines/dependencies.md
index bd0bfe9..83bdad6 100644
--- a/docs/api_guidelines/dependencies.md
+++ b/docs/api_guidelines/dependencies.md
@@ -95,8 +95,9 @@
more individual owners (e.g. NOT a group alias)
* Library **must** be approved by legal
-Please see Jetpack's [open-source policy page](open_source.md) for more details
-on using third-party libraries.
+Please see Jetpack's
+[open-source policy page](/company/teams/androidx/open_source.md) for more
+details on using third-party libraries.
### Types of dependencies {#dependencies-types}
@@ -145,8 +146,16 @@
between artifacts
([example](https://android-review.googlesource.com/c/platform/frameworks/support/+/2086029)).
-`core/core-ktx/build.gradle`: `dependencies { // Atomic group constraints {
-implementation(project(":core:core")) } }`
+`core/core-ktx/build.gradle`:
+
+```
+dependencies {
+ // Atomic group
+ constraints {
+ implementation(project(":core:core"))
+ }
+}
+```
In *extremely* rare cases, libraries may need to define a constraint on a
project that is not in its `studiow` project set, ex. a constraint between the
@@ -155,10 +164,16 @@
([example](https://android-review.googlesource.com/c/platform/frameworks/support/+/2160202))
to indicate the tip-of-tree version.
-`paging/paging-common.build.gradle`: `dependencies { // Atomic Group constraints
-{
-implementation("androidx.paging:paging-compose:${LibraryVersions.PAGING_COMPOSE}")
-}`
+`paging/paging-common/build.gradle`:
+
+```
+dependencies {
+ // Atomic group
+ constraints {
+ implementation("androidx.paging:paging-compose:${LibraryVersions.PAGING_COMPOSE}")
+ }
+}
+```
### System health {#dependencies-health}
@@ -184,16 +199,24 @@
Kotlin's coroutine library adds around 100kB post-shrinking. New libraries that
are written in Kotlin should prefer coroutines over `ListenableFuture`, but
existing libraries must consider the size impact on their clients. See
-[Asynchronous work with return values](#async-return) for more details on using
-Kotlin coroutines in Jetpack libraries.
+[Asynchronous work with return values](/company/teams/androidx/api_guidelines#async-return)
+for more details on using Kotlin coroutines in Jetpack libraries.
#### Guava {#dependencies-guava}
-The full Guava library is very large and *must not* be used. Libraries that
-would like to depend on Guava's `ListenableFuture` may instead depend on the
-standalone `com.google.guava:listenablefuture` artifact. See
-[Asynchronous work with return values](#async-return) for more details on using
-`ListenableFuture` in Jetpack libraries.
+The full Guava library is very large and should only be used in cases where
+there is a reasonable assumption that clients already depend on full Guava.
+
+For example, consider a library `androidx.foo:foo` implemented using Kotlin
+`suspend fun`s and an optional `androidx.foo:foo-guava` library that provides
+`ListenableFuture` interop wrappers with a direct dependency on
+`kotlinx.coroutines:kotlinx-coroutines-guava` and a transitive dependency on
+Guava.
+
+Libraries that only need `ListenableFuture` may instead depend on the standalone
+`com.google.guava:listenablefuture` artifact. See
+[Asynchronous work with return values](/company/teams/androidx/api_guidelines#async-return)
+for more details on using `ListenableFuture` in Jetpack libraries.
#### Protobuf {#dependencies-protobuf}
diff --git a/docs/api_guidelines/deprecation.md b/docs/api_guidelines/deprecation.md
index 0ca80db..4539ca6 100644
--- a/docs/api_guidelines/deprecation.md
+++ b/docs/api_guidelines/deprecation.md
@@ -27,7 +27,8 @@
APIs that are added during a pre-release cycle and marked as `@Deprecated`
within the same cycle, e.g. added in `alpha01` and deprecated in `alpha06`,
-[must be removed](versioning.md#beta-checklist) before moving to `beta01`.
+[must be removed](/company/teams/androidx/versioning.md#beta-checklist) before
+moving to `beta01`.
### Soft removal (`@removed` or `DeprecationLevel.HIDDEN`)
diff --git a/docs/api_guidelines/misc.md b/docs/api_guidelines/misc.md
index 7ab2bd8..34bc0ee 100644
--- a/docs/api_guidelines/misc.md
+++ b/docs/api_guidelines/misc.md
@@ -435,6 +435,17 @@
## Kotlin-specific guidelines {#kotlin}
+Generally speaking, Kotlin code should follow the compatibility guidelines
+outlined at:
+
+- The official Android Developers
+ [Kotlin-Java interop guide](https://developer.android.com/kotlin/interop)
+- Android API guidelines for
+ [Kotlin-Java interop](https://android.googlesource.com/platform/developers/docs/+/refs/heads/master/api-guidelines/index.md#kotin-interop)
+- Android API guidelines for
+ [asynchronous and non-blocking APIs](https://android.googlesource.com/platform/developers/docs/+/refs/heads/master/api-guidelines/async.md)
+- Library-specific guidance outlined below
+
### Nullability
#### Annotations on new Java APIs
diff --git a/docs/api_guidelines/modules.md b/docs/api_guidelines/modules.md
index 08e3433..b7bf26f 100644
--- a/docs/api_guidelines/modules.md
+++ b/docs/api_guidelines/modules.md
@@ -125,18 +125,23 @@
library, e.g. `androidx.room:room-testing`
* `-core` for a low-level artifact that *may* contain public APIs but is
primarily intended for use by other libraries in the group
-* `-ktx` for an Kotlin artifact that exposes idiomatic Kotlin APIs as an
- extension to a Java-only library (see
- [additional -ktx guidance](#module-ktx))
+* `-common` for a low-level, platform-agnostic Kotlin multi-platform artifact
+ intended for both client use and use by other libraries in the group
+* `-ktx` for a Kotlin artifact that exposes idiomatic Kotlin APIs as an
+ extension to a Java-only library. Note that new modules should be written in
+ Kotlin rather than using `-ktx` artifacts.
* `-samples` for sample code which can be inlined in documentation (see
[Sample code in Kotlin modules](#sample-code-in-kotlin-modules)
* `-<third-party>` for an artifact that integrates an optional third-party API
- surface, e.g. `-proto` or `-rxjava2`. Note that a major version is included
- in the sub-feature name for third-party API surfaces where the major version
- indicates binary compatibility (only needed for post-1.x).
+ surface, e.g. `-proto`, `-guava`, or `-rxjava2`. This is common for Kotlin
+ libraries adapting their async APIs for Java clients. Note that a major
+ version is included in the sub-feature name (ex. `rxjava3`) for third-party
+ API surfaces where the major version indicates binary compatibility (only
+ needed for post-1.x).
Artifacts **should not** use `-impl` or `-base` to indicate that a library is an
-implementation detail shared within the group. Instead, use `-core`.
+implementation detail shared within the group. Instead, use `-core` or `-common`
+as appropriate.
#### Splitting existing modules
@@ -263,21 +268,24 @@
external developers and should be considered a last-resort when backporting
behavior is not feasible.
-### Kotlin extension `-ktx` libraries {#module-ktx}
+### Extension libraries (`-ktx`, `-guava`, etc.) {#module-ktx}
New libraries should prefer Kotlin sources with built-in Java compatibility via
-`@JvmName` and other affordances of the Kotlin language; however, existing Java
-sourced libraries may benefit from extending their API surface with
-Kotlin-friendly APIs in a `-ktx` library.
+`@JvmName` and other affordances of the Kotlin language. They may optionally
+expose framework- or language-specific extension libraries like `-guava` or
+`-rxjava3`.
-A Kotlin extension library **may only** provide extensions for a single base
-library's API surface and its name **must** match the base library exactly. For
-example, `work:work-ktx` may only provide extensions for APIs exposed by
-`work:work`.
+Existing Java-sourced libraries may benefit from extending their API surface
+with Kotlin-friendly APIs in a `-ktx` extension library.
+
+Extension libraries **may only** provide extensions for a single base library's
+API surface and its name **must** match the base library exactly. For example,
+`work:work-ktx` may only provide extensions for APIs exposed by `work:work`.
Additionally, an extension library **must** specify an `api`-type dependency on
the base library and **must** be versioned and released identically to the base
library.
-Kotlin extension libraries *should not* expose new functionality; they should
-only provide Kotlin-friendly versions of existing Java-facing functionality.
+Extension libraries *should not* expose new functionality; they should only
+provide language- or framework-friendly versions of existing library
+functionality.
diff --git a/docs/api_guidelines/resources.md b/docs/api_guidelines/resources.md
index 3290271..2220c81 100644
--- a/docs/api_guidelines/resources.md
+++ b/docs/api_guidelines/resources.md
@@ -183,7 +183,7 @@
* never invoked.
*/
public final class MetadataHolderService {
- private MetadataHolderService() {}
+ public MetadataHolderService() {}
@Override
public IBinder onBind(Intent intent) {
diff --git a/docs/benchmarking.md b/docs/benchmarking.md
index f138231..ae5e3d6 100644
--- a/docs/benchmarking.md
+++ b/docs/benchmarking.md
@@ -9,7 +9,7 @@
This page is for MICRO benchmarks measuring CPU performance of small sections of
code. If you're looking for measuring startup or jank, see the guide for
-MACRObenchmarks [here](macrobenchmarking).
+MACRObenchmarks [here](/company/teams/androidx/macrobenchmarking.md).
### Writing the benchmark
diff --git a/docs/index.md b/docs/index.md
index a34d30b..6408bc9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -14,10 +14,11 @@
simplify and unify platform features, and other new features that target
developer pain points.
-For frequently asked questions, see the [General FAQ](faq.md).
+For frequently asked questions, see the
+[General FAQ](/company/teams/androidx/faq.md).
-To get started developing in AndroidX, see the [Getting started](onboarding.md)
-guide.
+To get started developing in AndroidX, see the
+[Getting started](/company/teams/androidx/onboarding.md) guide.
## Quick links
@@ -27,4 +28,4 @@
[public Issue Tracker component](http://issuetracker.google.com/issues/new?component=192731&template=842428)
for duplicates first, then file against the appropriate sub-component according
to the library package or infrastructure system. Learn more at
-[Issue tracking](onboarding.md#tracking-bugs).
+[Issue tracking](/company/teams/androidx/onboarding.md#tracking-bugs).
diff --git a/docs/issue_tracking.md b/docs/issue_tracking.md
index e8b9c84..f33022c 100644
--- a/docs/issue_tracking.md
+++ b/docs/issue_tracking.md
@@ -100,13 +100,13 @@
## Issue lifecycle
1. When an issue is reported, it is set to `Assigned` status for default
- assignee (typically the [library owner](owners.md)) with a priority of
- **P4**.
+ assignee (typically the [library owner](/company/teams/androidx/owners.md))
+ with a priority of **P4**.
1. Once an issue has been triaged by the assignee, its priority will be raised
from **P4** according to severity.
1. The issue may still be reassigned at this point.
- [Bug bounty](onboarding.md#bug-bounty) issues are likely to change
- assignees.
+ [Bug bounty](/company/teams/androidx/onboarding.md#bug-bounty) issues are
+ likely to change assignees.
1. A status of **Accepted** means the assignee is actively working on the
issue.
1. A status of **Fixed** means that the issue has been resolved in the
diff --git a/docs/kdoc_guidelines.md b/docs/kdoc_guidelines.md
index 0d7469c..fdea07c 100644
--- a/docs/kdoc_guidelines.md
+++ b/docs/kdoc_guidelines.md
@@ -93,7 +93,7 @@
maintenance. You can use multiple samples per KDoc, with text in between
explaining what the samples are showing. For more information on using
`@sample`, see the
-[API guidelines](/company/teams/androidx/api_guidelines.md#sample-code-in-kotlin-modules).
+[API guidelines](/company/teams/androidx/api_guidelines/index.md#sample-code-in-kotlin-modules).
### Do not link to the same identifier inside documentation
diff --git a/docs/macrobenchmarking.md b/docs/macrobenchmarking.md
index a908ea9..86d0536 100644
--- a/docs/macrobenchmarking.md
+++ b/docs/macrobenchmarking.md
@@ -36,7 +36,7 @@
for macrobenchmark explains how to use the library. This page focuses on
specifics to writing library macrobenchmarks in the AndroidX repo. If you're
looking for measuring CPU perf of individual functions, see the guide for
-MICRObenchmarks [here](benchmarking).
+MICRObenchmarks [here](/company/teams/androidx/benchmarking.md).
### Writing the benchmark
diff --git a/docs/manual_prebuilts_dance.md b/docs/manual_prebuilts_dance.md
index 0439d44..4dcbf63 100644
--- a/docs/manual_prebuilts_dance.md
+++ b/docs/manual_prebuilts_dance.md
@@ -1,7 +1,8 @@
# The Manual Prebuilts Dance™
-NOTE There is also a [script](releasing_detailed.md#the-prebuilts-dance™) that
-automates this step.
+NOTE There is also a
+[script](/company/teams/androidx/releasing_detailed.md#the-prebuilts-dance™)
+that automates this step.
Public-facing Jetpack library docs are built from prebuilts to reconcile our
monolithic docs update process with our independently-versioned library release
diff --git a/docs/onboarding.md b/docs/onboarding.md
index 56fd9f3..8c5cef7 100644
--- a/docs/onboarding.md
+++ b/docs/onboarding.md
@@ -6,9 +6,11 @@
make simple changes in Android Studio, and upload commits to Gerrit for review.
This page does **not** cover best practices for the content of changes. Please
-see [Life of a Jetpack Feature](loaf.md) for details on developing and releasing
-a library, [API Guidelines](api_guidelines/index.md) for best practices
-regarding public APIs and an overview of the constraints placed on changes.
+see [Life of a Jetpack Feature](/company/teams/androidx/loaf.md) for details on
+developing and releasing a library,
+[API Guidelines](/company/teams/androidx/api_guidelines/index.md) for best
+practices regarding public APIs and an overview of the constraints placed on
+changes.
## Workstation setup {#setup}
@@ -220,46 +222,52 @@
normally would for application or library development -- right-click on a test
or sample to run or debug it, search through classes, and so on.
-If you get a “Unregistered VCS root detected” message, click “Add root” to
-enable the Git/VCS integration for Android Studio.
-
-If you see any errors (red underlines), click Gradle's elephant button in the
-toolbar ("Sync Project with Gradle Files") and they should resolve once the
-build completes.
-
> NOTE: You should choose "Use project SDK" when prompted by Studio. If you
> picked "Android Studio SDK" by mistake, don't panic! You can fix this by
> opening `File > Project Structure > Platform Settings > SDKs` and manually
> setting the Android SDK home path to
> `<project-root>/prebuilts/fullsdk-<platform>`.
-> NOTE: If Android Studio's UI looks scaled up, ex. twice the size it should be,
-> you may need to add the following line to your `studio64.vmoptions` file using
-> `Help -> Edit Custom VM Options`:
->
-> ```
-> -Dsun.java2d.uiScale.enabled=false
-> ```
+### Troubleshooting {#studio-troubleshooting}
-> NOTE: We are aware of a bug where running `./studiow` does not result in
-> Android Studio application being launched.
+* If you've updated to macOS Ventura and receive a "App is damaged and cannot
+ be opened" message when running Studio, *do not* move the app to the Trash.
+ Cancel out of the dialog and open macOS `System Settings > Gatekeeper`, look
+ for `"Android Studio" was blocked`, and click `Open Anyway` to grant an
+ exception. Alternatively, you can navigate to the Studio `.app` file under
+ `frameworks/support/studio` and run it once using `Control+Click` and `Open`
+ to automatically grant an exception.
+* If you've updated to macOS Ventura and receive a "xcrun: error: invalid
+ active developer path" message when running Studio, reinstall Xcode using
+ `xcode-select --install`. If that does not work, you will need to download
+ Xcode.
+* If you get a “Unregistered VCS root detected” message, click “Add root” to
+ enable the Git/VCS integration for Android Studio.
+* If you see any errors (red underlines), click Gradle's elephant button in
+ the toolbar (or `File > Sync Project with Gradle Files`) and they should
+ resolve once the build completes.
+* If you run `./studiow` with a new project set but you're still seeing the
+ old project set in `Project`, use `File > Sync Project with Gradle Files` to
+ force a re-sync.
+* If Android Studio's UI looks scaled up, ex. twice the size it should be, you
+ may need to add the following line to your `studio64.vmoptions` file using
+ `Help > Edit Custom VM Options`: `-Dsun.java2d.uiScale.enabled=false`
+* If you don't see a specific Gradle task listed in Studio's Gradle pane,
+ check the following:
+ * Studio might be running a different project subset than the one
+ intended. For example, `./studiow main` only loads the `main` set of
+ androidx projects; run `./studiow compose` to load the tasks specific to
+ Compose.
+ * Gradle tasks aren't being loaded. Under Studio's settings =>
+ Experimental, make sure that "Do not build Gradle task list during
+ Gradle sync" is unchecked. Note that unchecking this can reduce Studio's
+ performance.
If in the future you encounter unexpected errors in Studio and you want to check
for the possibility it is due to some incorrect settings or other generated
files, you can run `./studiow --clean main <project subset>` or `./studiow
--reinstall <project subset>` to clean generated files or reinstall Studio.
-> Tip: If you don't see a specific Gradle task listed in Studio's Gradle pane,
-> check the following:
->
-> * Studio might be running a different project subset than the one intended.
-> For example, `./studiow main` only loads the `main` set of androidx
-> projects; run `./studiow compose` to load the tasks specific to Compose.
->
-> * Gradle tasks aren't being loaded. Under Studio's settings => Experimental,
-> make sure that "Do not build Gradle task list during Gradle sync" is
-> unchecked. (Note that unchecking this can reduce Studio's performance)
-
### Enabling Compose `@Preview` annotation previews
Add the following dependencies to your project's `build.gradle`:
@@ -372,9 +380,8 @@
./gradlew core:core:assemble --strict
```
-To build every module, run the Lint verifier, verify the public API surface, and
-generate the local Maven repository artifact, use the `createArchive` Gradle
-task:
+To build every module and generate the local Maven repository artifact, use the
+`createArchive` Gradle task:
```shell
./gradlew createArchive
@@ -468,45 +475,20 @@
NOTE `./gradlew tasks` always has the canonical task information! When in doubt,
run `./gradlew tasks`
-#### Javadocs
-
-To build API reference docs for tip-of-tree Java source code, run the Gradle
-task:
-
-```
-./gradlew doclavaDocs
-```
-
-Places the documentation in
-`{androidx-main}/out/androidx/docs-tip-of-tree/build/javadoc`
-
-#### KotlinDocs
-
-To build API reference docs for tip-of-tree Kotlin source code, run the Gradle
-task:
-
-```
-./gradlew dokkaKotlinDocs
-```
-
-Places the documentation in
-`{androidx-main}/out/androidx/docs-tip-of-tree/build/dokkaKotlinDocs`
-
-#### Dackka docs
+#### Generate Docs
To build API reference docs for both Java and Kotlin source code using Dackka,
run the Gradle task:
```
-./gradlew dackkaDocs
+./gradlew docs
```
Location of generated refdocs:
* docs-public (what is published to DAC):
- `{androidx-main}/out/androidx/docs-public/build/dackkaDocs`
-* docs-tip-of-tree:
- `{androidx-main}/out/androidx/docs-tip-of-tree/build/dackkaDocs`
+ `{androidx-main}/out/androidx/docs-public/build/docs`
+* docs-tip-of-tree: `{androidx-main}/out/androidx/docs-tip-of-tree/build/docs`
The generated docs are plain HTML pages with links that do not work locally.
These issues are fixed when the docs are published to DAC, but to preview a
@@ -532,40 +514,21 @@
[d.android.com](http://d.android.com), run the Gradle command:
```
-./gradlew zipDoclavaDocs
+./gradlew zipDocs
```
-This will create the artifact
-`{androidx-main}/out/dist/doclava-public-docs-0.zip`. This command builds docs
-based on the version specified in
+This will create the artifact `{androidx-main}/out/dist/docs-public-0.zip`. This
+command builds docs based on the version specified in
`{androidx-main-checkout}/frameworks/support/docs-public/build.gradle` and uses
the prebuilt checked into
`{androidx-main-checkout}/prebuilts/androidx/internal/androidx/`. We
colloquially refer to this two step process of (1) updating `docs-public` and
(2) checking in a prebuilt artifact into the prebuilts directory as
-[The Prebuilts Dance](releasing_detailed.md#the-prebuilts-dance™). So, to build
-javadocs that will be published to
+[The Prebuilts Dance](/company/teams/androidx/releasing_detailed.md#the-prebuilts-dance™).
+So, to build javadocs that will be published to
https://developer.android.com/reference/androidx/packages, both of these steps
need to be completed.
-Once you done the above steps, Kotlin docs will also be generated, with the only
-difference being that we use the Gradle command:
-
-```
-./gradlew zipDokkaDocs
-```
-
-This will create the artifact `{androidx-main}/out/dist/dokka-public-docs-0.zip`
-
-To generate a zip artifact for both Java and Kotlin source code using Dackka:
-
-```
-./gradlew zipDackkaDocs
-```
-
-This will create the artifact
-`{androidx-main}/out/dist/dackka-public-docs-0.zip`
-
### Updating public APIs {#updating-public-apis}
Public API tasks -- including tracking, linting, and verifying compatibility --
@@ -595,6 +558,10 @@
If you change the public APIs without updating the API file, your module will
still build **but** your CL will fail Treehugger presubmit checks.
+NOTE The `updateApi` task does not generate versioned API files (e.g.
+`1.0.0-beta01.txt`) during a library's `alpha`, `rc` or stable cycles. The task
+will always generate `current.txt` API files.
+
#### What are all these files in `api/`? {#updating-public-apis-glossary}
Historical API surfaces are tracked for compatibility and docs generation
@@ -604,11 +571,11 @@
* `<version>.txt`: Public API surface, tracked for compatibility
* `restricted_<version>.txt`: `@RestrictTo` API surface, tracked for
compatibility where necessary (see
- [Restricted APIs](api_guidelines/index.md#restricted-api))
+ [Restricted APIs](/company/teams/androidx/api_guidelines/index.md#restricted-api))
* `public_plus_experimental_<version>.txt`: Public API surface plus
`@RequiresOptIn` experimental API surfaces used for documentation (see
- [Experimental APIs](api_guidelines/index.md#experimental-api)) and API
- review
+ [Experimental APIs](/company/teams/androidx/api_guidelines/index.md#experimental-api))
+ and API review
### Release notes & the `Relnote:` tag {#relnote}
@@ -794,7 +761,8 @@
are referencing new framework APIs, you will need to wait for the framework
changes to land in an SDK build (or build it yourself) and then land in both
prebuilts/fullsdk and prebuilts/sdk. See
-[Updating SDK prebuilts](playbook.md#prebuilts-fullsdk) for more information.
+[Updating SDK prebuilts](/company/teams/androidx/playbook.md#prebuilts-fullsdk)
+for more information.
#### How do I handle refactoring a framework API referenced from a library?
@@ -836,8 +804,8 @@
or `support-\*-demos` (e.g. `support-v4-demos` or `support-leanback-demos`). You
can run them by clicking `Run > Run ...` and choosing the desired application.
-See the [Testing](testing.md) page for more resources on writing, running, and
-monitoring tests.
+See the [Testing](/company/teams/androidx/testing.md) page for more resources on
+writing, running, and monitoring tests.
### AVD Manager
@@ -937,7 +905,7 @@
### Using in a Gradle build
-To make these artifacts visible to Gradle, you need to add it as a respository:
+To make these artifacts visible to Gradle, you need to add it as a repository:
```groovy
allprojects {
@@ -960,7 +928,7 @@
to use a snapshot artifact, the version in your `build.gradle` will need to be
updated to `androidx.<groupId>:<artifactId>:X.Y.Z-SNAPSHOT`
-For example, to use the `core:core:1.2.0-SHAPSHOT` snapshot, you would add the
+For example, to use the `core:core:1.2.0-SNAPSHOT` snapshot, you would add the
following to your `build.gradle`:
```
@@ -1032,7 +1000,7 @@
full m2repository to avoid version issues of other modules. You can either take
the unzipped directory from
`<path-to-checkout>/out/dist/top-of-tree-m2repository-##.zip`, or from
-`<path-to-checkout>/out/androidx/build/support_repo/` after buiding `androidx`.
+`<path-to-checkout>/out/androidx/build/support_repo/` after building `androidx`.
Here is an example of replacing the RecyclerView module:
```shell
@@ -1047,7 +1015,8 @@
### How do I measure library size? {#library-size}
Method count and bytecode size are tracked in CI
-[alongside benchmarks](benchmarking.md#monitoring) to detect regressions.
+[alongside benchmarks](/company/teams/androidx/benchmarking.md#monitoring) to
+detect regressions.
For local measurements, use the `:reportLibraryMetrics` task. For example:
@@ -1072,3 +1041,21 @@
[Overview page](https://developer.android.com/reference/kotlin/androidx/compose/runtime/package-summary)
includes content from
[compose-runtime-documentation.md](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/compose-runtime-documentation.md).
+
+### How do I enable MultiDex for my library?
+
+Go to your project/app level build.gradle file, and add
+
+```
+android {
+ defaultConfig {
+ multiDexEnabled = true
+ }
+}
+```
+
+as well as `androidTestImplementation(libs.multidex)` to the dependenices block.
+
+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/open_source.md b/docs/open_source.md
index 173d1e77..392dc34 100644
--- a/docs/open_source.md
+++ b/docs/open_source.md
@@ -29,7 +29,7 @@
#### Closed-source dependencies
In specific cases, libraries *may* include closed-source dependencies. See the
-[Open-source compatibility](api_guidelines/dependencies.md#dependencies-aosp)
+[Open-source compatibility](/company/teams/androidx/api_guidelines/index.md#dependencies-aosp)
section of the API Guidelines for implementation details.
### Examples of products that are _not_ open-source
diff --git a/docs/principles.md b/docs/principles.md
index 523c87f..a2d2a42 100644
--- a/docs/principles.md
+++ b/docs/principles.md
@@ -60,8 +60,9 @@
to choose between a variety of services as the backing implementation
- Comply with AndroidX checks and policies such as API tracking and style
checks
-- See [Integrating proprietary components](open_source.md) for guidance on
- using closed-source and proprietary libraries and services
+- See
+ [Integrating proprietary components](/company/teams/androidx/open_source.md)
+ for guidance on using closed-source and proprietary libraries and services
### 6. Written using language-idiomatic APIs
diff --git a/docs/team.md b/docs/team.md
index 0c61aa4b..0149376 100644
--- a/docs/team.md
+++ b/docs/team.md
@@ -4,7 +4,7 @@
<!--*
# Document freshness: For more information, see go/fresh-source.
-freshness: { owner: 'alanv' reviewed: '2022-06-10' }
+freshness: { owner: 'alanv' reviewed: '2022-12-09' }
*-->
## What we do
diff --git a/docs/testability.md b/docs/testability.md
index 45d4b6d..5a1a773 100644
--- a/docs/testability.md
+++ b/docs/testability.md
@@ -39,11 +39,11 @@
improvement.
To get started with sample code, see
-[Sample code in Kotlin modules](api_guidelines.md#sample-code-in-kotlin-modules)
+[Sample code in Kotlin modules](/company/teams/androidx/api_guidelines/index.md#sample-code-in-kotlin-modules)
for information on writing samples that can be referenced from API reference
documentation or
-[Project directory structure](api_guidelines.md#module-structure) for module
-naming guidelines if you'd like to create a basic test app.
+[Project directory structure](/company/teams/androidx/api_guidelines/index.md#module-structure)
+for module naming guidelines if you'd like to create a basic test app.
### Avoiding side-effects {#side-effects}
@@ -308,8 +308,9 @@
state has been reached or the requested action has been completed. This might
mean adding listeners, callbacks, `ListenableFuture`s, or `LiveData`.
-See [Asynchronous work](api_guidelines.md#async) in the API Guidelines for more
-information on exposing the state of asynchronous work to clients.
+See [Asynchronous work](/company/teams/androidx/api_guidelines/index.md#async)
+in the API Guidelines for more information on exposing the state of asynchronous
+work to clients.
### Calling `Thread.sleep()` as a synchronization barrier
diff --git a/docs/testing.md b/docs/testing.md
index b59a240..b6fde3a 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -30,7 +30,7 @@
NOTE For best practices on writing libraries in a way that makes it easy for end
users -- and library developers -- to write tests, see the
-[Testability](testability.md) guide.
+[Testability](/company/teams/androidx/testability.md) guide.
### What gets tested, and when {#affected-module-detector}
@@ -255,7 +255,7 @@
* Validation of API usability and developer experience, when paired with a use
case or critical user journey
* Sample documentation, when embedded into API reference docs using the
- [`@sample` and `@Sampled` annotations](api_guidelines.md#sample-usage)
+ [`@sample` and `@Sampled` annotations](/company/teams/androidx/api_guidelines/index.md#sample-usage)
### Legacy test apps {#testapps-legacy}
@@ -273,4 +273,4 @@
AndroidX supports benchmarking - locally with Studio/Gradle, and continuously in
post-submit. For more information on how to create and run benchmarks, see
-[Benchmarking](benchmarking.md).
+[Benchmarking](/company/teams/androidx/benchmarking.md).
diff --git a/docs/versioning.md b/docs/versioning.md
index b7b5a1a..12434a5 100644
--- a/docs/versioning.md
+++ b/docs/versioning.md
@@ -6,24 +6,31 @@
including the expectations at each cycle and criteria for moving to the next
cycle or SemVer revision.
-## Semantic versioning
+## Semantic versioning and binary compatibility {#semver}
Artifacts follow strict [semantic versioning](http://semver.org) for binary
-compatibility with an added inter-version sequence of pre-release revisions. The
-version for a finalized release artifact will follow the format
+compatibility with an added inter-version sequence of pre-release revisions.
+Versions for finalized release artifacts, which are available on
+[Google Maven](https://maven.google.com) will follow the format
`<major>.<minor>.<bugfix>` with an optional `-<alpha|beta|rc><nn>` suffix.
-Internal or nightly releases (via [androidx.dev](http://androidx.dev)) use the
-`-SNAPSHOT` suffix.
+Internal or nightly releases, which are available on
+[androidx.dev](http://androidx.dev), use the `-SNAPSHOT` suffix.
-### Source compatibility
+### Behavioral and source compatibility {#compat}
-Libraries are encouraged -- but not required -- to preserve source compatibility
-across minor versions. Strictly requiring source compatibility would require
-major version bumps when implementing quality-of-life improvements such as
-nullability annotations or generics, which would be
-[disruptive to the library ecosystem](#major-implications).
+Libraries are required to preserve *behavioral compatibility* -- APIs must
+behave as described in their documentation -- across minor versions. Special
+consideration must also be made for changes to undocumented behavior, as
+developers may have made their own assumptions about API contracts based on
+observed behavior.
-### Notation
+Libraries are strongly encouraged to preserve *source compatibility* across
+minor versions. Strictly requiring source compatibility would require major
+version bumps when implementing quality-of-life improvements such as nullability
+annotations or generics, which would be [disruptive](#major-implications) to the
+library ecosystem.
+
+### Notation {#notation}
Major (`x.0.0`)
: An artifact's major version indicates a guaranteed forward-compatibility
@@ -33,7 +40,7 @@
Minor (`1.x.0`)
: Minor indicates compatible public API changes. This number is incremented
when APIs are added, including the addition of
- [`@Deprecated` annotations](api_guidelines.md#deprecation-and-removal).
+ [`@Deprecated` annotations](/company/teams/androidx/api_guidelines/index.md#deprecation-and-removal).
Binary compatibility must be preserved between minor version changes.
Bugfix (`1.0.x`)
@@ -41,7 +48,7 @@
taken to ensure that existing clients are not broken, including clients that
may have been working around long-standing broken behavior.
-#### Pre-release cycles
+#### Pre-release cycles {#prerelease}
Alpha (`1.0.0-alphaXX`)
: Feature development and API stabilization phase.
@@ -231,8 +238,9 @@
`publish=true` or create an `api` directory) and remain enabled
* May add/remove APIs within `alpha` cycle, but deprecate/remove cycle is
strongly recommended.
- * May use [experimental APIs](api_guidelines.md#experimental-api) across
- same-version group boundaries
+ * May use
+ [experimental APIs](/company/teams/androidx/api_guidelines/index.md#experimental-api)
+ across same-version group boundaries
* Testing
* All changes **should** be accompanied by a `Test:` stanza
* All pre-submit and post-submit tests are passing
@@ -264,13 +272,13 @@
* All APIs from alpha undergoing deprecate/remove cycle must be removed
* The final removal of a `@Deprecated` API should occur in alpha, not
in beta
- * Must not use [experimental APIs](api_guidelines.md#experimental-api)
+ * Must not use
+ [experimental APIs](/company/teams/androidx/api_guidelines#experimental-api)
across same-version group boundaries
* Testing
* All public APIs are tested
* All pre-submit and post-submit tests are enabled (e.g. all suppressions
are removed) and passing
- * Your library passes `./gradlew library:checkReleaseReady`
* Use of experimental Kotlin features (e.g. `@OptIn`) must be audited for
stability
* All dependencies are `beta`, `rc`, or stable
@@ -336,22 +344,19 @@
- The version of your library listed in `androidx-main` should *always* be
higher than the version publically 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 (nickanthony@) CC'd
+ be handled by the library owner, with the Jetpack TPM (natnaelbelay@) CC'd
for API+1.
-
- Version increments in release branches will need to follow the guide
- [How to update your version on a release branch](release_branches.md#update-your-version)
-
+ [How to update your version on a release branch](/company/teams/androidx/release_branches.md#update-your-version)
- When you're ready for `rc01`, the increment to `rc01` should be done in
`androidx-main` and then your release branch should be snapped to that
- build. See the guide [Snap your release branch](release_branches.md#snap) on
- how to do this. After the release branch is snapped to that build, you will
- need to update your version in `androidx-main` to `alpha01` of the next
+ build. See the guide
+ [Snap your release branch](/company/teams/androidx/release_branches.md#snap)
+ on how to do this. After the release branch is snapped to that build, you
+ will need to update your version in `androidx-main` to `alpha01` of the next
minor (or major) version.
### How to update your version
@@ -369,9 +374,10 @@
## `-ktx` Modules {#ktx}
-[Kotlin extension libraries](api_guidelines.md#module-ktx) (`-ktx`) follow the
-same versioning requirements as other libraries, but with one exception: they
-must match the version of the Java libraries that they extend.
+[Kotlin extension libraries](/company/teams/androidx/api_guidelines/index.md#module-ktx)
+(`-ktx`) follow the same versioning requirements as other libraries, but with
+one exception: they must match the version of the Java libraries that they
+extend.
For example, let's say you are developing a Java library
`androidx.foo:foo-bar:1.1.0-alpha01` and you want to add a Kotlin extension
@@ -389,10 +395,6 @@
Generally, these occur during the batched bi-weekly (every 2 weeks) release
because all tip-of-tree dependencies will need to be released too.
-### Are there restrictions on when or how often an alpha can ship?
-
-Nope.
-
### 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
@@ -405,5 +407,5 @@
### How often can a beta release?
-As often as needed, however, releases outside of the bi-weekly (every 2 weeks)
+As often as needed; however, releases outside of the bi-weekly (every 2 weeks)
release will need to get approval from the TPM (natnaelbelay@).
