Project import generated by Copybara.
PiperOrigin-RevId: 362153315
Change-Id: Id591e2d5bfd457b9a285b9e3c9a99a1b720a96b0
diff --git a/docs/api_guidelines.md b/docs/api_guidelines.md
index 7905b89..88a2b26 100644
--- a/docs/api_guidelines.md
+++ b/docs/api_guidelines.md
@@ -1223,21 +1223,64 @@
<tr>
<td><code>RestrictTo.Scope</code></td>
<td>Visibility by Maven coordinate</td>
+ <td>Versioning</td>
</tr>
<tr>
<td><code>LIBRARY</code></td>
<td><code>androidx.concurrent:concurrent</code></td>
+ <td>No compatibility gurantees (same as private)</td>
</tr>
<tr>
<td><code>LIBRARY_GROUP</code></td>
<td><code>androidx.concurrent:*</code></td>
+ <td>Semantic versioning (including deprecation)</td>
</tr>
<tr>
<td><code>LIBRARY_GROUP_PREFIX</code></td>
<td><code>androidx.*:*</code></td>
+ <td>Semantic versioning (including deprecation)</td>
</tr>
</table>
+#### `@IntDef` `@StringDef` and `@LongDef` and visibility
+
+All `@IntDef`, `@StringDef`, and `@LongDef` will be stripped from resulting
+artifacts to avoid issues where compiler inlining constants removes information
+as to which `@IntDef` defined the value of `1`. The annotations are extracted
+and packaged separately to be read by Android Studio and lint which enforces the
+types in application code.
+
+* Libraries _must_ `@hide` all `@IntDef`, `@StringDef`, and `@LongDef`
+ declarations.
+* Libraries _must_ expose constants used to define the `@IntDef` etc at the
+ same Java visibility as the hidden `@IntDef`
+* Libraries _should_ also use @RestrictTo to create a warning when the type
+ used incorrectly.
+
+Here is a complete example of an `@IntDef`
+
+```java
+// constants match Java visibility of ExifStreamType
+// code outside this module interacting with ExifStreamType uses these constants
+public static final int STREAM_TYPE_FULL_IMAGE_DATA = 1;
+public static final int STREAM_TYPE_EXIF_DATA_ONLY = 2;
+
+/** @hide */
+@RestrictTo(RestrictTo.Scope.LIBRARY) // Don't export ExifStreamType outside module
+@Retention(RetentionPolicy.SOURCE)
+@IntDef({
+ STREAM_TYPE_FULL_IMAGE_DATA,
+ STREAM_TYPE_EXIF_DATA_ONLY,
+})
+public @interface ExifStreamType {}
+```
+
+Java visibilty should be set as appropriate for the code in question (`private`,
+`package` or `public`) and is unrelated to hiding.
+
+For more, read the section in
+[Android API Council Guidelines](https://android.googlesource.com/platform/developers/docs/+/refs/heads/master/api-guidelines/index.md#no-public-typedefs)
+
### Constructors {#constructors}
#### View constructors {#view-constructors}
diff --git a/docs/kdoc_guidelines.md b/docs/kdoc_guidelines.md
new file mode 100644
index 0000000..c53ba8c
--- /dev/null
+++ b/docs/kdoc_guidelines.md
@@ -0,0 +1,176 @@
+# Kotlin documentation (KDoc) guidelines
+
+[TOC]
+
+This guide contains documentation guidance specific to Jetpack Kotlin APIs.
+General guidance from
+s.android.com/api-guidelines#docs
+should still be followed, this guide contains extra guidelines specifically for
+Kotlin documentation. For detailed information on KDoc's supported tags and
+syntax, see the
+[official documentation](https://kotlinlang.org/docs/kotlin-doc.html).
+
+## Guidelines for writing KDoc
+
+### Every parameter / property in a function / class should be documented
+
+Without an explicit `@param` / `@property` tag, a table entry for a particular
+parameter / property will not be generated. Make sure to add tags for *every*
+element to generate full documentation for an API.
+
+```kotlin {.good}
+/**
+ * ...
+ *
+ * @param1 ...
+ * @param2 ...
+ * @param3 ...
+ */
+fun foo(param1: Int, param2: String, param3: Boolean) {}
+```
+
+### Consider using all available tags to add documentation for elements
+
+Kotlin allows defining public APIs in a concise manner, which means that it can
+be easy to forget to write documentation for a specific element. For example,
+consider the following contrived example:
+
+```kotlin
+class Item<T>(val label: String, content: T)
+
+fun <T> Item<T>.appendContent(content: T): Item<T> { ... }
+```
+
+The class declaration contains:
+
+* A generic type - `T`
+* A property (that is also a constructor parameter) - `label`
+* A constructor parameter - `content`
+* A constructor function - `Item(label, content)`
+
+The function declaration contains:
+
+* A generic type - `T`
+* A receiver - `Item<T>`
+* A parameter - `content`
+* A return type - `Item<T>`
+
+When writing KDoc, consider adding documentation for each element:
+
+```kotlin {.good}
+/**
+ * An Item represents content inside a list...
+ *
+ * @param T the type of the content for this Item
+ * @property label optional label for this Item
+ * @param content the content for this Item
+ * @constructor creates a new Item
+ */
+class Item<T>(val label: String? = null, content: T)
+
+/**
+ * Appends [content] to [this] [Item], returning a new [Item].
+ *
+ * @param T the type of the content in this [Item]
+ * @receiver the [Item] to append [content] to
+ * @param content the [content] that will be appended to [this]
+ * @return a new [Item] representing [this] with [content] appended
+ */
+fun <T> Item<T>.appendContent(content: T): Item<T> { ... }
+```
+
+You may omit documentation for simple cases, such as a constructor for a data
+class that just sets properties and has no side effects, but in general it can
+be helpful to add documentation for all parts of an API.
+
+### Use `@sample` for each API that represents a standalone feature, or advanced behavior for a feature
+
+`@sample` allows you to reference a Kotlin function as sample code inside
+documentation. The body of the function will be added to the generated
+documentation inside a code block, allowing you to show usage for a particular
+API. Since this function is real Kotlin code that will be compiled and linted
+during the build, the sample will always be up to date with the API, reducing
+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).
+
+### Do not link to the same identifier inside documentation
+
+Avoid creating self-referential links:
+
+```kotlin {.bad}
+/**
+ * [Item] is ...
+ */
+class Item
+```
+
+These links are not actionable, as they will take the user to the same element
+they are already reading - instead refer to the element in the matching case
+without a link:
+
+```kotlin {.good}
+/**
+ * Item is ...
+ */
+class Item
+```
+
+## Javadoc - KDoc differences
+
+Some tags are shared between Javadoc and KDoc, such as `@param`, but there are
+notable differences between the syntax and tags supported. Unsupported syntax /
+tags do not currently show as an error in the IDE / during the build, so be
+careful to look out for the following important changes.
+
+### Hiding documentation
+
+Using `@suppress` will stop documentation being generated for a particular
+element. This is equivalent to using `@hide` in Android Javadoc.
+
+### Deprecation
+
+To mark an element as deprecated, use the `@Deprecated` annotation on the
+corresponding declaration, and consider including a `ReplaceWith` fragment to
+suggest the replacement for deprecated APIs.
+
+```kotlin {.good}
+package androidx.somepackage
+
+@Deprecated(
+ "Renamed to Bar",
+ replaceWith = ReplaceWith(
+ expression = "Bar",
+ // import(s) to be added
+ "androidx.somepackage.Bar"
+ )
+)
+class Foo
+
+class Bar
+```
+
+This is equivalent to using the `@deprecated` tag in Javadoc, but allows
+specifying more detailed deprecation messages, and different 'severity' levels
+of deprecation. For more information see the documentation for
+[@Deprecated](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-deprecated/).
+
+### Linking to elements
+
+To link to another element, put its name in square brackets. For example, to
+refer to the class `Foo`, use `[Foo]`. This is equivalent to `{@link Foo}` in
+Javadoc. You can also use a custom label, similar to Markdown: `[this
+class][Foo]`.
+
+### Code spans
+
+To mark some text as code, surround the text with a backtick (\`) as in
+Markdown. For example, \`true\`. This is equivalent to `{@code true}` in
+Javadoc.
+
+### Inline markup
+
+KDoc uses Markdown for inline markup, as opposed to Javadoc which uses HTML. The
+IDE / build will not show a warning if you use HTML tags such as `<p>`, so be
+careful not to accidentally use these in KDoc.
diff --git a/docs/onboarding.md b/docs/onboarding.md
index e0e72d9..ed9452b 100644
--- a/docs/onboarding.md
+++ b/docs/onboarding.md
@@ -217,6 +217,11 @@
logs can be helpful for reporting issues to the team that manages our git
servers.
+NOTE If `repo upload` or any `git` command hangs and causes your CPU usage to
+skyrocket (e.g. your laptop fan sounds like a jet engine), then you may be
+hitting a rare issue with Git-on-Borg and HTTP/2. You can force `git` and `repo`
+to use HTTP/1.1 with `git config --global http.version HTTP/1.1`.
+
## Building {#building}
### Modules and Maven artifacts {#modules-and-maven-artifacts}
@@ -228,11 +233,12 @@
./gradlew core:core:assemble
```
-Use the `-Pandroidx.allWarningsAsErrors` to make warnings fail your build (same
-as presubmits):
+To make warnings fail your build (same as presubmit), use the `--strict` flag,
+which our gradlew expands into a few correctness-related flags including
+`-Pandroidx.allWarningsAsErrors`:
```shell
-./gradlew core:core:assemble -Pandroidx.allWarningsAsErrors
+./gradlew core:core:assemble --strict
```
To build every module, run the Lint verifier, verify the public API surface, and
@@ -243,11 +249,11 @@
./gradlew createArchive
```
-To run the complete build task that our build servers use, use the
-`buildOnServer` Gradle task:
+To run the complete build task that our build servers use, use the corresponding
+shell script:
```shell
-./gradlew buildOnServer
+./busytown/androidx.sh
```
### Attaching a debugger to the build
diff --git a/docs/principles.md b/docs/principles.md
index c498b10..6151a2c 100644
--- a/docs/principles.md
+++ b/docs/principles.md
@@ -58,8 +58,8 @@
- Avoid proprietary services or closed-source libraries for core
functionality, and instead provide integration points that allow a developer
to choose between a variety of services as the backing implementation
-- See [Integrating proprietary components] for guidance on using closed-source
- and proprietary libraries and services
+- See [Integrating proprietary components](open_source.md) for guidance on
+ using closed-source and proprietary libraries and services
### 6. Written using language-idiomatic APIs
diff --git a/docs/testability.md b/docs/testability.md
new file mode 100644
index 0000000..52d60a9
--- /dev/null
+++ b/docs/testability.md
@@ -0,0 +1,194 @@
+# Testability
+
+[TOC]
+
+## How to write testable libraries
+
+When developers use a Jetpack library, it should be easy to write reliable and
+automated tests for their own code's functionality. In most cases, tests written
+against a library will need to interact with that library in some way -- setting
+up preconditions, reaching synchronization points, making calls -- and the
+library should provide necessary functionality to enable such tests, either
+through public APIs or optional `-testing` artifacts.
+
+**Testability**, in this document, means how easily and effectively the users of
+a library can create tests for apps that use that library.
+
+NOTE Tests that check the behavior of a library have a different mission than
+tests made by app developers using that library; however, library developers may
+find themselves in a similar situation when writing tests for sample code.
+
+Often, the specifics of testability will vary from library to library and there
+is no one way of providing it. Some libraries have enough public API surface,
+others provide additional testing artifacts (e.g.
+[Lifecycle Runtime Testing artifact](https://maven.google.com/web/index.html?q=lifecycle#androidx.lifecycle:lifecycle-runtime-testing)).
+
+The best way to check if your library is testable is to try to write a sample
+app with tests. Unlike regular library tests, these apps will be limited to the
+public API surface of the library.
+
+Keep in mind that a good test for a sample app should have:
+
+* [No side effects](#side-effects)
+* [No dependencies on time / looper (except for UI)](#external-dependencies)
+* [No private API calls](#private-apis)
+* [No assumptions on undefined library behavior](#undefined-behavior)
+
+If you are able to write such tests for your library, you are good to go. If you
+struggled or found yourself writing duplicate testing code, there is room for
+improvement.
+
+To get started with sample code, see
+[Sample code in Kotlin modules](api_guidelines.md#sample-code-in-kotlin-modules)
+for information on writing samples that can be referenced from API reference
+documentation or [Project directory structure](policies.md#directory-structure)
+for module naming guidelines if you'd like to create a basic test app.
+
+### Avoiding side-effects {#side-effects}
+
+#### Ensure proper scoping for your library a.k.a. Avoid Singletons
+
+Singletons are usually bad for tests as they live across different tests,
+opening the gates for possible side-effects between tests. When possible, try to
+avoid using singletons. If it is not possible, consider providing a test
+artifact that will reset the state of the singleton between tests.
+
+#### Side effects due to external resources
+
+Sometimes, your library might be controlling resources on the device in which
+case even if it is not a singleton, it might have side-effects. For instance,
+Room, being a database library, inherently modifies a file on the disk. To allow
+proper isolated testing, Room provides a builder option to create the database
+[in memory](https://developer.android.com/reference/androidx/room/Room#inMemoryDatabaseBuilder\(android.content.Context,%20java.lang.Class%3CT%3E\))
+A possible alternative solution could be to provide a test rule that will
+properly close databases after each test.
+
+If your library needs an inherently singleton resource (e.g. `WorkManager` is a
+wrapper around `JobScheduler` and there is only 1 instance of it provided by the
+system), consider providing a testing artifact. To provide isolation for tests,
+the WorkManager library ships a
+[separate testing artifact](https://developer.android.com/topic/libraries/architecture/workmanager/how-to/integration-testing)
+
+### "External" dependencies {#external-dependencies}
+
+#### Allow configuration of external resource dependencies
+
+A common example of this use case is libraries that do multi-threaded
+operations. For Kotlin libraries, this is usually achieved by receiving a
+coroutine context or scope. For Java libraries, it is commonly an `Executor`. If
+you have a case like this, make sure it can be passed as a parameter to your
+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)
+
+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)
+
+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
+allow setting it. For example, the Lifecycle package depends on the main thread
+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)
+to change them.
+
+#### Fakes for external dependencies
+
+Sometimes, the developer might want to track side effects of your library for
+end to end testing. For instance, if your library provides some functionality
+that might decide to toggle bluetooth, outside developer's direct control, it
+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)
+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.
+
+NOTE There is a fine balance between making a library configurable and making
+configuration a nightmare for the developer. You should try to always have
+defaults for these configurable objects to ensure your library is easy to use
+while still testable when necessary.
+
+### Avoiding the need for private API calls in tests {#private-apis}
+
+#### Provide additional functionality for tests
+
+There are certain situations where it could be useful to provide more APIs that
+only make sense in the scope of testing. For example, a `Lifecycle` class has
+methods that are bound to the main thread but developers may want to have other
+tests that rely on lifecycle but do not run on the main thread (or even on an
+emulator). For such cases, you may create APIs that are testing only to allow
+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)
+an instance of it that will not enforce thread restrictions.
+
+NOTE Even though the implementation referenced above is acceptable, it is always
+better to create such functionality in additional testing artifacts when
+possible.
+
+### Avoiding assumptions in app code for library behavior {#undefined-behavior}
+
+#### Provide fakes for common classes in a `-testing` artifact
+
+In some cases, the developer might need an instance of a class provided by your
+library but does not want to (or cannot) initiate it in tests. Moreover,
+behavior of such classes might not be fully defined for edge cases, making it
+difficult for developers to mock them.
+
+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)
+for the `LifecycleOwner` class that can be manipulated in tests to create
+different use cases.
+
+## Document how to test with your library
+
+Even when your library is fully testable, it is often not clear for a developer
+to know which APIs are safe to call in tests and when. Providing guidance on
+[d.android.com](https://d.android.com) will make it much easier for the
+developer to start testing with your library.
+
+## Testability anti-patterns
+
+When writing tests against your APIs, look out for the following anti-patterns.
+
+### Calling `Instrumentation.waitForIdleSync()` as a synchronization barrier
+
+The `waitForIdle()` and `waitForIdleSync()` methods claim to "(Synchronously)
+wait for the application to be idle." and may seem like reasonable options when
+there is no obvious way to observe whether an action has completed; however,
+these methods know nothing about the context of the test and return when the
+main thread's message queue is empty.
+
+```java {.bad}
+view.requestKeyboardFocus();
+Instrumentation.waitForIdleSync();
+sendKeyEvents(view, "1234");
+// There is no guarantee that `view` has keyboard focus yet.
+device.pressEnter();
+```
+
+In apps with an active UI animation, the message queue is _never empty_. If the
+app is waiting for a callback across IPC, the message queue may be empty despite
+the test not reaching the desired state.
+
+In some cases, `waitForIdleSync()` introduces enough of a delay that unrelated
+asynchronous actions happen to have completed by the time the method returns;
+however, this delay is purely coincidental and eventually leads to flakiness.
+
+Instead, find a reliable synchronization barrier that guarantees the expected
+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.
diff --git a/docs/testing.md b/docs/testing.md
index f757002..0832b44 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -24,6 +24,10 @@
and
[`Parameterized`](https://junit.org/junit4/javadoc/4.12/org/junit/runners/Parameterized.html).
+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.
+
### What gets tested, and when
We use the
