Project import generated by Copybara.
PiperOrigin-RevId: 438823546
Change-Id: Ibc483c11d058e263597e99ffee8b3abbbe65c860
diff --git a/docs/api_guidelines.md b/docs/api_guidelines.md
index e732660..257c7da 100644
--- a/docs/api_guidelines.md
+++ b/docs/api_guidelines.md
@@ -92,6 +92,22 @@
./create_project.py androidx.foo foo-bar
```
+If you see an error message `No module named 'toml'` try the following steps.
+
+* Install necessary tools if they are not already installed
+ * (Linux) `sudo apt-get install virtualenv python3-venv`
+ * (Mac) `pip3 install virtualenv`
+* Create a virtual environment with `virtualenv androidx_project_creator` (you
+ can choose another name for your virtualenv if you wish).
+* Install the `toml` library in your virtual env with
+ `androidx_project_creator/bin/pip3 install toml`
+* Run the project creator script from your virtual env with
+ `androidx_project_creator/bin/python3
+ ./development/project-creator/create_project.py androidx.foo foo-bar`
+* Delete your virtual env with `rm -rf ./androidx-project_creator`
+ * virtualenv will automatically .gitignore itself, but you may want to to
+ remove it anyway.
+
#### Common sub-feature names {#module-naming-subfeature}
* `-testing` for an artifact intended to be used while testing usages of your
@@ -1622,14 +1638,47 @@
#### With return values {#async-return}
+###### Kotlin
+
Traditionally, asynchronous work on Android that results in an output value
would use a callback; however, better alternatives exist for libraries.
-Kotlin libraries should prefer
+Kotlin libraries should consider
[coroutines](https://kotlinlang.org/docs/reference/coroutines-overview.html) and
-`suspend` functions, but please refer to the guidance on
-[allowable dependencies](#dependencies-coroutines) before adding a new
-dependency on coroutines.
+`suspend` functions for APIs according to the following rules, but please refer
+to the guidance on [allowable dependencies](#dependencies-coroutines) before
+adding a new dependency on coroutines.
+
+Kotlin suspend fun vs blocking | Behavior
+------------------------------------ | --------------------------
+blocking function with @WorkerThread | API is blocking
+suspend | API is async (e.g. Future)
+
+In general, do not introduce a suspend function entirely to switch threads for
+blocking calls. To do so correctly requires that we allow the developer to
+configure the Dispatcher. As there is already a coroutines-based API for
+changing dispatchers (withContext) that the caller may use to switch threads, it
+is unecessary API overhead to provide a duplicate mechanism. In addition, it
+unecessary limits callers to coroutine contexts.
+
+```kotlin
+// DO expose blocking calls as blocking calls
+@WorkerThread
+fun blockingCall()
+
+// DON'T wrap in suspend functions (only to switch threads)
+suspend fun blockingCallWrappedInSuspend(
+ dispatcher: CoroutineDispatcher = Dispatchers.Default
+) = withContext(dispatcher) { /* ... */ }
+
+// DO expose async calls as suspend funs
+suspend fun asyncCall(): ReturnValue
+
+// DON'T expose async calls as a callback-based API (for the main API)
+fun asyncCall(executor: Executor, callback: (ReturnValue) -> Unit)
+```
+
+###### Java
Java libraries should prefer `ListenableFuture` and the
[`CallbackToFutureAdapter`](https://developer.android.com/reference/androidx/concurrent/futures/CallbackToFutureAdapter)
@@ -2011,14 +2060,11 @@
new lint check, and it is prohibitively expensive / not possible to fix the
errors generated by enabling this lint check.
-To update a lint baseline (`lint-baseline.xml`) after you have fixed issues,
-first **manually delete the `lint-baseline.xml` file** for your project and then
-run the `lintDebug` task for your project with the argument
-`-PupdateLintBaseline`.
+To update a lint baseline (`lint-baseline.xml`) after you have fixed issues, run
+the `updateLintBaseline` task.
```shell
-rm core/core/lint-baseline.xml
-./gradlew :core:core:lintDebug -PupdateLintBaseline
+./gradlew :core:core:updateLintBaseline
```
## Metalava API Lint
diff --git a/docs/index.md b/docs/index.md
index ff3003a..0a9bae4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -35,7 +35,7 @@
developed new policies around versioning and release, and developed tools to
make it easy for developers to migrate.
-Revision 28.0.0 of the Support Library, which launched as stable in September
+Revision `28.0.0` of the Support Library, which launched as stable in September
2018, was the last feature release in the `android.support` package. There will
be no further releases under Support Library packaging.
@@ -46,4 +46,5 @@
Have a bug or feature request? Please check our
[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.
+to the library package or infrastructure system. Learn more at
+[Issue tracking](onboarding.md#tracking-bugs).
diff --git a/docs/lint_guide.md b/docs/lint_guide.md
index 9a0fdb7..49b20707 100644
--- a/docs/lint_guide.md
+++ b/docs/lint_guide.md
@@ -1,4 +1,4 @@
-# Adding custom Lint checks
+# Adding custom lint checks
[TOC]
@@ -16,7 +16,7 @@
### Create a module
-If this is the first Lint rule for a library, you will need to create a module
+If this is the first lint rule for a library, you will need to create a module
by doing the following:
Include the project in the top-level `settings.gradle` file so that it shows up
@@ -57,7 +57,7 @@
type = LibraryType.LINT
mavenVersion = LibraryVersions.MYLIBRARY
mavenGroup = LibraryGroups.MYLIBRARY
- inceptionYear = "2019"
+ inceptionYear = "2022"
description = "Lint checks for MyLibrary"
}
```
@@ -74,25 +74,32 @@
```kotlin
class MyLibraryIssueRegistry : IssueRegistry() {
- override val api = 11
override val minApi = CURRENT_API
+ override val api = 13
override val issues get() = listOf(MyLibraryDetector.ISSUE)
+ override val vendor = Vendor(
+ feedbackUrl = "https://issuetracker.google.com/issues/new?component=######",
+ identifier = "androidx.mylibrary",
+ vendorName = "Android Open Source Project",
+ )
}
```
-The maximum version this Lint check will will work with is defined by `api =
-11`, where versions `0`-`11` correspond to Lint/Studio versions `3.0`-`3.11`.
+The maximum version this lint check will will work with is defined by `api =
+13`. Typically, this should track `CURRENT_API`.
-`minApi = CURRENT_API` sets the lowest version of Lint that this will work with.
+`minApi = CURRENT_API` sets the lowest version of the Lint tool that this will
+work with.
-`CURRENT_API` is defined by the Lint API version against which your project is
-compiled, as defined in the module's `build.gradle` file. Jetpack Lint modules
-should compile using the Lint API version referenced in
-[Dependencies.kt](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:buildSrc/public/src/main/kotlin/androidx/build/dependencies/Dependencies.kt;l=176).
+`CURRENT_API` is defined by the Lint tool API version against which your project
+is compiled, as defined in the module's `build.gradle` file. Jetpack lint check
+modules should compile using the Lint tool API version referenced in
+[libs.versions.toml](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:gradle/libs.versions.toml;l=8).
-We guarantee that our Lint checks work with the versions referenced by `minApi`
+We guarantee that our lint checks work with the versions referenced by `minApi`
and `api` by running our tests with both versions. For newer versions of Android
-Studio (and consequently, Lint) the API variable will need to be updated.
+Studio (and consequently, the Lint tool) the API variable will need to be
+updated.
The `IssueRegistry` requires a list of all of the issues to check. You must
override the `IssueRegistry.getIssues()` method. Here, we override that method
@@ -100,14 +107,14 @@
[Example `IssueRegistry` Implementation](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:fragment/fragment-lint/src/main/java/androidx/fragment/lint/FragmentIssueRegistry.kt)
-There are 4 primary types of Lint checks:
+There are 4 primary types of lint checks:
1. Code - Applied to source code, ex. `.java` and `.kt` files
1. XML - Applied to XML resource files
1. Android Manifest - Applied to `AndroidManifest.xml`
1. Gradle - Applied to Gradle configuration files, ex. `build.gradle`
-It is also possible to apply Lint checks to compiled bytecode (`.class` files)
+It is also possible to apply lint checks to compiled bytecode (`.class` files)
or binary resource files like images, but these are less common.
## PSI & UAST mapping
@@ -250,7 +257,7 @@
## Code detector
-These are Lint checks that will apply to source code files -- primarily Java and
+These are lint checks that will apply to source code files -- primarily Java and
Kotlin, but can also be used for other similar file types. All code detectors
that analyze Java or Kotlin files should implement the
[SourceCodeScanner](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-api/src/main/java/com/android/tools/lint/detector/api/SourceCodeScanner.kt).
@@ -259,7 +266,7 @@
#### Calls to specific methods
-##### getApplicableMethodNames
+##### `getApplicableMethodNames`
This defines the list of methods where lint will call the visitMethodCall
callback.
@@ -268,10 +275,10 @@
override fun getApplicableMethodNames(): List<String>? = listOf(METHOD_NAMES)
```
-##### visitMethodCall
+##### `visitMethodCall`
-This defines the callback that Lint will call when it encounters a call to an
-applicable method.
+This defines the callback that the Lint tool will call when it encounters a call
+to an applicable method.
```kotlin
override fun visitMethodCall(context: JavaContext, node: UCallExpression, method: PsiMethod) {}
@@ -279,7 +286,7 @@
#### Calls to specific class instantiations
-##### getApplicableConstructorTypes
+##### `getApplicableConstructorTypes`
```kotlin
override fun getApplicableConstructorTypes(): List<String>? = listOf(CLASS_NAMES)
@@ -293,13 +300,13 @@
#### Classes that extend given superclasses
-##### getApplicableSuperClasses
+##### `getApplicableSuperClasses`
```kotlin
override fun applicableSuperClasses(): List<String>? = listOf(CLASS_NAMES)
```
-##### visitClass
+##### `visitClass`
```kotlin
override fun visitClass(context: JavaContext, declaration: UClass) {}
@@ -322,12 +329,12 @@
### Method call analysis
-#### resolve()
+#### `resolve()`
Resolves into a `UCallExpression` or `UMethod` to perform analysis requiring the
method body or containing class.
-#### ReceiverType
+#### `receiverType`
Each `UCallExpression` has a `receiverType` corresponding to the `PsiType` of
the receiver of the method call.
@@ -381,10 +388,14 @@
Since this class also depends on the `LifecycleOwner` class it is necessary to
create another stub for this.
+NOTE `package-info.java` cannot be represented by a source stub and must be
+provided as bytecode. See [Updating bytecode](#tips-bytecode) for tips on using
+bytecode in lint tests.
+
## XML resource detector
-These are Lint rules that will apply to resource files including `anim`,
-`layout`, `values`, etc. Lint rules being applied to resource files should
+These are lint checks that will apply to resource files including `anim`,
+`layout`, `values`, etc. lint checks being applied to resource files should
extend
[`ResourceXmlDetector`](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-api/src/main/java/com/android/tools/lint/detector/api/ResourceXmlDetector.java).
The `Detector` must define the issue it is going to detect, most commonly as a
@@ -418,7 +429,7 @@
visitElement(context: XmlContext, element: Element)
```
-#### appliesTo
+#### `appliesTo`
This determines the
[ResourceFolderType](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:layoutlib-api/src/main/java/com/android/resources/ResourceFolderType.java)
@@ -430,19 +441,19 @@
}
```
-#### getApplicableElements
+#### `getApplicableElements`
-This defines the list of elements where Lint will call your visitElement
-callback method when encountered.
+This defines the list of elements where the Lint tool will call your
+`visitElement` callback method when encountered.
```kotlin
override fun getApplicableElements(): Collection<String>? = Collections.singleton(ELEMENT)
```
-#### visitElement
+#### `visitElement`
This defines the behavior when an applicable element is found. Here you normally
-place the actions you want to take if a violation of the Lint check is found.
+place the actions you want to take if a violation of the lint check is found.
```kotlin
override fun visitElement(context: XmlContext, element: Element) {
@@ -471,11 +482,11 @@
### Testing
-You need tests for two things. First, you must test that the API Lint version is
-properly set. That is done with a simple `ApiLintVersionTest` class. It asserts
-the api version code set earlier in the `IssueRegistry()` class. This test
-intentionally fails in the IDE because different Lint API versions are used in
-the studio and command line.
+You need tests for two things. First, you must test that the Lint tool API
+version is properly set. That is done with a simple `ApiLintVersionTest` class.
+It asserts the API version code set earlier in the `IssueRegistry()` class. This
+test intentionally fails in the IDE because different Lint tool API versions are
+used in Studio and the command line.
Example `ApiLintVersionTest`:
@@ -515,7 +526,7 @@
[`TestLintResult`](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-tests/src/main/java/com/android/tools/lint/checks/infrastructure/TestLintResult.kt).
`TestLintResult` provides methods for checking the outcome of the provided
`TestLintTask`. `ExpectClean()` means the output is expected to be clean because
-the lint rule was followed. `Expect()` takes a string literal of the expected
+the lint check was followed. `Expect()` takes a string literal of the expected
output of the `TestLintTask` and compares the actual result to the input string.
If a quick fix was implemented, you can check that the fix is correct by calling
`checkFix()` and providing the expected output file stub.
@@ -536,7 +547,7 @@
### API surface
-#### checkDslPropertyAssignment
+#### `checkDslPropertyAssignment`
Analyzes each DSL property assignment, providing the property and value strings.
@@ -558,14 +569,14 @@
be quote enclosed in the value parameter. Any constant values cannot be resolved
to their values.
-The cookie parameters should be used for reporting Lint errors. To report an
-issue on the value, use `context.getLocation(statementCookie)`.
+The cookie parameters should be used for reporting lint check errors. To report
+an issue on the value, use `context.getLocation(statementCookie)`.
-## Enabling Lint for a library
+## Enabling lint checks for a library
-Once the Lint module is implemented we need to enable it for the desired
+Once the lint module is implemented we need to enable it for the desired
library. This can be done by adding a `lintPublish` rule to the `build.gradle`
-of the library the Lint check should apply to.
+of the library the lint check should apply to.
```
lintPublish(project(':mylibrary:mylibrary-lint'))
@@ -586,16 +597,16 @@
### Analyzing multiple different file types
-Sometimes it is necessary to implement multiple different scanners in a Lint
+Sometimes it is necessary to implement multiple different scanners in a lint
detector. For example, the
[Unused Resource](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/UnusedResourceDetector.java)
-Lint check implements an XML and SourceCodeScanner in order to determine if
+lint check implements an XML and SourceCodeScanner in order to determine if
resources defined in XML files are ever references in the Java/Kotlin source
code.
#### File type iteration order
-The Lint system processes files in a predefined order:
+The Lint tool processes files in a predefined order:
1. Manifests
1. Android XML Resources (alphabetical by folder type)
@@ -616,7 +627,7 @@
contains most of the canonical names for Android core library classes, as well
as XML tag names.
-### Updating bytecode and checksum in tests
+### Updating bytecode and checksum in tests {#tips-bytecode}
When updating a file that is used in a lint test, the following error may appear
when running tests:
diff --git a/docs/onboarding.md b/docs/onboarding.md
index dbd3f84..933a00c 100644
--- a/docs/onboarding.md
+++ b/docs/onboarding.md
@@ -28,7 +28,7 @@
```
Then, modify `~/.zshrc` (or `~/.bash_profile` if using `bash`) to ensure you can
-find local binaries from the command line. We assume you're using zsh, but the
+find local binaries from the command line. We assume you're using `zsh`, but the
following should work with `bash` as well.
```shell
@@ -36,7 +36,7 @@
```
You will need to either start a new terminal session or run `source ~/.zshrc`
-(or `source ~/.bash_profile` if using bash) to pick up the new path.
+(or `source ~/.bash_profile` if using `bash`) to pick up the new path.
If you encounter an SSL `CERTIFICATE_VERIFY_FAILED` error or warning about
Python 2 being no longer supported, you will need to install Python 3 and alias
@@ -57,16 +57,20 @@
information about SSL/TLS certificate validation and the running the "Install
Certificates.command".
+Next, double-check where your `repo
Next, open your `~/.zshrc` (or `~/.bash_profile` if using bash) and add the
following lines to wrap the `repo` command:
```shell
# Force repo to run with Python3
function repo() {
- command python3 "$(which repo)" $@
+ command python3 ~/bin/repo $@
}
```
+Make sure to reload the updated profile by starting a new terminal session or
+running `source ~/.zshrc` or `source ~/.bash_profile` as appropriate.
+
### Windows {#setup-win}
Sorry, Windows is not a supported platform for AndroidX development.
@@ -204,6 +208,9 @@
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.
@@ -258,6 +265,23 @@
[Android documentation](https://source.android.com/setup/create/coding-tasks#workflow)
for a high level overview of this basic workflow.
+If you see the following prompt, choose `always`:
+
+```
+Run hook scripts from https://android.googlesource.com/platform/manifest (yes/always/NO)?
+```
+
+If the upload succeeds, you'll see an output like:
+
+```
+remote:
+remote: New Changes:
+remote: https://android-review.googlesource.com/c/platform/frameworks/support/+/720062 Further README updates
+remote:
+```
+
+To edit your change, use `git commit --amend`, and re-upload.
+
NOTE If you encounter issues with `repo upload`, consider running upload with
trace enabled, e.g. `GIT_DAPPER_TRACE=1 repo --trace upload . --cbr -y`. These
logs can be helpful for reporting issues to the team that manages our git
@@ -425,7 +449,7 @@
```
Places the documentation in
-`{androidx-main}/out/dist/out/androidx/docs-tip-of-tree/build/dokkaKotlinDocs`
+`{androidx-main}/out/androidx/docs-tip-of-tree/build/dokkaKotlinDocs`
#### Dackka docs
@@ -439,9 +463,9 @@
Location of generated refdocs:
* docs-public (what is published to DAC):
- `{androidx-main}/out/dist/out/androidx/docs-public/build/dackkaDocs`
+ `{androidx-main}/out/androidx/docs-public/build/dackkaDocs`
* docs-tip-of-tree:
- `{androidx-main}/out/dist/out/androidx/docs-tip-of-tree/build/dackkaDocs`
+ `{androidx-main}/out/androidx/docs-tip-of-tree/build/dackkaDocs`
#### Release docs
@@ -646,6 +670,15 @@
that you have checked in. You will reference this constant in your library's
`build.gradle` dependencies.
+#### Dependency verification
+
+If the new dependency you are importing is unsigned, or is signed with a new,
+unrecognized key, then you will need to add new dependency verification metadata
+to indicate to Gradle that this new dependency is trusted. Instructions for how
+to do this are currently in the
+[README](https://android.googlesource.com/platform/frameworks/support/+/androidx-main/gradle/README.md)
+in the development subfolder
+
#### Updating an existing dependency
If an older version of a dependency prebuilt was already checked in, please
@@ -684,7 +717,30 @@
100% of their public API surface. Additionally, all CLs must include a `Test:`
stanza indicating which tests were used to verify correctness. Any CLs
implementing bug fixes are expected to include new regression tests specific to
-the issue being fixed
+the issue being fixed.
+
+### Running Tests
+
+#### Single Test Class or Method
+
+1. Open the desired test file in Android Studio.
+2. Right-click on a test class or @Test method name and select `Run FooBarTest`
+
+#### Full Test Package
+
+1. In the project side panel open the desired module.
+2. Find the directory with the tests
+3. Right-click on the directory and select `Run androidx.foobar`
+
+### Running Sample Apps
+
+The AndroidX repository has a set of Android applications that exercise AndroidX
+code. These applications can be useful when you want to debug a real running
+application, or reproduce a problem interactively, before writing test code.
+
+These applications are named either `<libraryname>-integration-tests-testapp`,
+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.
@@ -848,32 +904,20 @@
repository artifact:
```shell
-# Creates <path-to-checkout>/out/dist/sdk-repo-linux-m2repository-##.zip
+# Creates <path-to-checkout>/out/androidx/build/support_repo/
./gradlew createArchive
```
-Next, take the ZIP output from this task and extract the contents to the Android
-SDK path that you are using for your alternate (non-AndroidX) version of Android
-Studio. For example, you may be using `~/Android/SDK/extras` if you are using
-the default Android Studio SDK for app development or
-`prebuilts/fullsdk-linux/extras` if you are using fullsdk for platform
-development.
-
-```shell
-# Creates or overwrites android/m2repository
-cd <path-to-sdk>/extras
-unzip <path-to-checkout>/out/dist/top-of-tree-m2repository-##.zip
-```
-
-In the project's 'build.gradle' within 'repositories' notify studio of the
-location of m2repository:
+Using for your alternate (non-AndroidX) version of Android Studio open the
+project's 'build.gradle' and add the following within 'repositories' to make
+Android Gradle Plugin look for binaries in newly built repository:
```groovy
allprojects {
repositories {
...
maven {
- url "<path-to-sdk>/extras/m2repository"
+ url "<path-to-sdk>/out/androidx/build/support_repo/"
}
}
}
diff --git a/docs/testability.md b/docs/testability.md
index ea5c3e3..b4f0918 100644
--- a/docs/testability.md
+++ b/docs/testability.md
@@ -80,14 +80,14 @@
library.
NOTE Android API Guidelines require that methods accepting a callback
-[must also take an Executor](https://android.googlesource.com/platform/developers/docs/+/refs/heads/master/api-guidelines/index.md#callbacks-listener)
+[must also take an Executor](https://android.googlesource.com/platform/developers/docs/+/refs/heads/master/api-guidelines/index.md#provide-executor)
For example, the Room library allows developers to
[pass different executors](https://developer.android.com/reference/androidx/room/RoomDatabase.Builder#setQueryExecutor\(java.util.concurrent.Executor\))
for background query operations. When writing a test, developers can invoke this
with a custom executor where they can track work completion.
-* [sample test](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-master-dev:room/integration-tests/kotlintestapp/src/androidTest/java/androidx/room/integration/kotlintestapp/test/SuspendingQueryTest.kt;l=672)
+* [sample test](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:room/integration-tests/kotlintestapp/src/androidTest/java/androidx/room/integration/kotlintestapp/test/SuspendingQueryTest.kt;l=672)
If the external resource you require does not make sense as a public API, such
as a main thread executor, then you can provide a testing artifact which will
@@ -95,7 +95,7 @@
executor to function but for an application, customizing it does not make sense
(as there is only 1 "pre-defined" main thread for an app). For testing purposes,
the Lifecycle library provides a testing artifact which includes
-[TestRules](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-master-dev:arch/core-testing/src/main/java/androidx/arch/core/executor/testing/CountingTaskExecutorRule.java)
+[TestRules](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:arch/core-testing/src/main/java/androidx/arch/core/executor/testing/CountingTaskExecutorRule.java)
to change them.
#### Fakes for external dependencies
@@ -106,7 +106,7 @@
might be a good idea to have an interface for that functionality and also
provide a fake that can record such calls. If you don't think that interface
makes sense as a library configuration, you can
-[restrict](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-master-dev:annotation/annotation/src/main/java/androidx/annotation/RestrictTo.java)
+[restrict](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:annotation/annotation/src/main/java/androidx/annotation/RestrictTo.java)
that interface to your library group and provide a testing artifacts with the
fake so that developer can observe side effects only in tests while you can
avoid creating unnecessary APIs.
@@ -128,7 +128,7 @@
developers to use them only in tests while giving them the confidence that it
will behave as close as possible to a real implementation. For the case above,
`LifecycleRegistry` provides an API to
-[create](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-master-dev:lifecycle/lifecycle-runtime/src/main/java/androidx/lifecycle/LifecycleRegistry.java;l=334)
+[create](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:lifecycle/lifecycle-runtime/src/main/java/androidx/lifecycle/LifecycleRegistry.java;l=340)
an instance of it that will not enforce thread restrictions.
NOTE Even though the implementation referenced above is acceptable, it is always
@@ -147,7 +147,7 @@
For such cases, it is a good practice to provide a fake implementation out of
the box that can be controlled in tests. For example, the Lifecycle library
provides a
-[fake implementation](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-master-dev:lifecycle/lifecycle-runtime-testing/src/main/java/androidx/lifecycle/testing/TestLifecycleOwner.kt)
+[fake implementation](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:lifecycle/lifecycle-runtime-testing/src/main/java/androidx/lifecycle/testing/TestLifecycleOwner.kt)
for the `LifecycleOwner` class that can be manipulated in tests to create
different use cases.
diff --git a/docs/testing.md b/docs/testing.md
index d6ad752..2829821 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -32,7 +32,7 @@
users -- and library developers -- to write tests, see the
[Testability](testability.md) guide.
-### What gets tested, and when
+### What gets tested, and when {#affected-module-detector}
We use the
[AffectedModuleDetector](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:buildSrc/private/src/main/kotlin/androidx/build/dependencyTracker/AffectedModuleDetector.kt)
@@ -50,9 +50,9 @@
The remaining devices are tested only in postsubmit. In postsubmit, all host and
device tests are run for all modules.
-### Test annotations
+### Test annotations {#annotations}
-#### Test size and runners
+#### Test size and runners {#test-size}
All device tests *should* be given a size annotation, which is one of:
@@ -72,7 +72,7 @@
`@MediumTest` | 1000ms
`@LargeTest` | 100000ms
-#### Disabling tests
+#### Disabling tests {#disabling-tests}
To disable a device-side test in presubmit testing only -- but still have it run
in postsubmit -- use the
@@ -85,7 +85,7 @@
annotation. Do *not* use Android's `@Suppress` annotation, which only works with
Android test runners and will *not* work for host-side tests.
-#### Filtering devices
+#### Filtering devices {#filtering-devices}
To restrict a test to a range of SDKs, use
[`@SdkSuppress`](https://developer.android.com/reference/androidx/test/filters/SdkSuppress)
@@ -97,8 +97,8 @@
// Target SDKs 17 through 19, inclusive
@SdkSuppress(minSdkVersion = 17, maxSdkVersion = 19)
-// Target pre-release SDK R only
-@SdkSuppress(minSdkVersion = Build.VERSION_CODES.R, isCodeName = "R")
+// Target pre-release SDK T only
+@SdkSuppress(minSdkVersion = Build.VERSION_CODES.TIRAMISU, codeName = "Tiramisu")
```
You may also gate portions of test implementation code using `SDK_INT` or
@@ -112,7 +112,7 @@
that a bug in Cuttlefish, so please file those bugs instead of only looking for
a workaround.
-### Animations in tests
+### Animations in tests {#animations}
Animations are disabled for tests by default. This helps avoid flakes due to
timing and also makes tests faster.
@@ -121,7 +121,7 @@
animations for a particular test or test class. For those cases, you can use the
[`AnimationDurationScaleRule`](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:testutils/testutils-runtime/src/main/java/androidx/testutils/AnimationDurationScaleRule.kt).
-### Robolectric
+### Robolectric {#robolectric}
Robolectric tests are supported in AndroidX; however, if you targeting a
pre-release version of the Android SDK then you may see an error like
@@ -155,9 +155,12 @@
NOTE You can reuse the emulator and system images from a "normal" installation
of Android Studio by linking the `emulator` and `system_images` directories to a
-standard Android SDK path and restarting Android Studio: `cd
+standard Android SDK path and restarting Android Studio. **This is set up
+automatically by `studiow` on Google-managed devices with a standard Android SDK
+path.** In other cases, it may be set up manually with something like: `cd
prebuilts/fullsdk-darwin ln -s ~/Library/Android/sdk/emulator emulator ln -s
-~/Library/Android/sdk/system-images system-images`
+~/Library/Android/sdk/system-images system-images` (substituting `fullsdk-linux`
+and your local SDK path as appropriate)
## Debugging with platform SDK sources {#sources}
diff --git a/docs/versioning.md b/docs/versioning.md
index 42bec31..b54025f 100644
--- a/docs/versioning.md
+++ b/docs/versioning.md
@@ -2,25 +2,29 @@
[TOC]
+This page covers Jetpack's usage of Semantic Versioning and pre-release cycles,
+including the expectations at each cycle and criteria for moving to the next
+cycle or SemVer revision.
+
## Semantic versioning
-Artifacts follow strict semantic versioning. The version for a finalized release
-will follow the format `<major>.<minor>.<bugfix>` with an optional
-`-<alpha|beta|rc><nn>` suffix. Internal or nightly releases should use the
-`-SNAPSHOT` suffix to indicate that the release bits are subject to change.
-
-Also check out the [Versioning FAQ](faq.md#version).
+Artifacts follow strict [semantic versioning](http://semver.org) with an added
+inter-version sequence of pre-release revisions. The version for a finalized
+release 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)) should use the `-SNAPSHOT` suffix.
### Notation
Major (`x.0.0`)
: An artifact's major version indicates a guaranteed forward-compatibility
- window. For example, a developer could update an artifact versioned `2.0.0`
- to `2.7.3` without taking any additional action.
+ window. The number is incremented only when introducing breaking API or
+ behavioral changes.
Minor (`1.x.0`)
: Minor indicates compatible public API changes. This number is incremented
- when APIs are added, including the addition of `@Deprecated` annotations.
+ when APIs are added, including the addition of
+ [`@Deprecated` annotations](api_guidelines.md#deprecation-and-removal).
Binary compatibility must be preserved between minor version changes.
Bugfix (`1.0.x`)
@@ -34,17 +38,13 @@
: Feature development and API stabilization phase.
Beta (`1.0.0-betaXX`)
-: Functional stabilization phase.
+: Functional stabilization phase. Suitable for production use.
RC (`1.0.0-rcXX`)
: Verification phase.
Stable (no-suffix)
-: Final releases are well-tested, both by internal tests and external clients,
- and their API surface is reviewed and finalized. While APIs may be
- deprecated in future versions and removed in subsequent major version bumps,
- any APIs added at this stage should be considered semi-permanent as major
- version bumps are [strongly discouraged](#major-implications).
+: Recommended for production use.
### Major (`x.0.0`) {#major}
@@ -52,7 +52,8 @@
For example, a developer could update an artifact versioned `2.0.0` to `2.7.3`
without taking any additional action; however, updating from `2.7.3` to `3.0.0`
may require a complete rewrite of their application or cause conflicts with
-their dependencies.
+their dependencies. Major version bumps are
+[strongly discouraged](#major-implications).
#### When to increment {#major-when}
@@ -342,7 +343,7 @@
1. Update the version listed in `frameworks/support/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 reqired
+ of your library. For other versions, this step is not required
1. Verify changes with `./gradlew checkApi verifyDependencyVersions`.
1. Commit these change as one commit.
1. Upload these changes to Gerrit for review.
@@ -352,14 +353,14 @@
## `-ktx` Modules {#ktx}
-Kotlin Extension modules (`-ktx`) for regular Java modules follow the same
-requirements, but with one exception. They must match the version of the Java
-module that they extend.
+[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.
-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
-module `androidx.foo:foo-bar-ktx` module. Your new `androidx.foo:foo-bar-ktx`
-module will start at version `1.1.0-alpha01` instead of `1.0.0-alpha01`.
+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
+library `androidx.foo:foo-bar-ktx`. Your new `androidx.foo:foo-bar-ktx` library
+will start at version `1.1.0-alpha01` instead of `1.0.0-alpha01`.
If your `androidx.foo:foo-bar` module was in version `1.0.0-alpha06`, then the
-kotlin extension module would start in version `1.0.0-alpha06`.
+Kotlin extension module would start in version `1.0.0-alpha06`.
