docs/principles.md

# Jetpack principles

[TOC]

## Ethos of Jetpack

To create components, tools, and guidance that make it quick and easy to build
great Android apps, including contributions from Google and the open-source
community.

## Core principles of a Jetpack library

Jetpack libraries provide the following guarantees to Android Developers:

*formatted as “Jetpack libraries are…” with sub-points “Libraries should…”*

### 1. Optimized for external client adoption

-   Work for first-party clients and may even have optional modules tailored
    specifically to first-party needs, but primary functionality should target
    external developers.
-   Measure success by 3p client adoption, followed by 1p client adoption.

### 2. Designed to satisfy real-world use cases

-   Meet developers where they are and solve the problems that they have
    building apps.
    -   In most cases, that means going beyond simple parity with existing
        platform APIs and features.
-   Expose modules that are tightly-scoped to **developer pain points**.
    -   Smaller building blocks for external developers by scoping disjoint use
        cases that are likely not to co-exist in a single app to individual
        modules.
-   Implement layered complexity with **simple top-level APIs**.
    -   Complicated use case support must not be at the expense of increasing
        API complexity for the most common simpler use cases.
-   Have **backing data or a researched hypothesis** (research, demand, etc.) to
    prove the library is necessary and sufficient.
-   Include only functionality that is relevant to the library's stated use
    case.
    -   End user and developer trust depend on libraries being transparent about
        their operation. See
        [Functionality](/docs/api_guidelines#functionality) in
        the API Guidelines for details.

### 3. Aware of the existing developer ecosystem

-   Avoid reinventing the wheel. Do not create a new library where one already
    exists that is accepted by the community as a best practice.

### 4. Consistent with the rest of Jetpack

-   Ensure that concepts learned in one component can be seen and understood in
    other components.
-   Leverage Jetpack and community standards. For example:
    -   For async work, uses Kotlin coroutines and/or Kotlin flow.
    -   For data persistence, uses Jetpack DataStore for simple and small data
        and uses Room for more complicated Data.

### 5. Developed as open-source and compatible with AOSP Android

-   Expose a unified developer-facing API surface across the Android ecosystem.
-   Develop in AOSP to provide visibility into new features and bug fixes and
    encourage external participation.
-   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
-   Comply with AndroidX checks and policies such as API tracking and style
    checks.

See [Integrating proprietary components](/docs/open_source.md)
for guidance on using closed-source and proprietary libraries and services.

### 6. Written using language-idiomatic APIs

-   Write APIs that feel natural for clients using both
    [Kotlin](https://developer.android.com/kotlin/interop) and Java.

### 7. Compatible with a broad range of API levels

-   Support older platforms and API levels according to client needs
-   Provide continued maintenance to ensure compatibility with newer platforms.
-   Design with the expectation that every Jetpack API is **write-once,
    run-everywhere** for Android with graceful degradation where necessary.

### 8. Integrated with best practices

-   Guide developers toward using existing Jetpack best-practice libraries,
    including Architecture Components.
-   In cases that involve user interfaces, e.g. any reference to `View` classes,
    provide non-`View` functional parity when used with the Compose UI toolkit.

### 9. Designed for tooling and testability

-   Write adequate unit and integration tests for the library itself.
-   Provide developers with an accompanying testing story for integration
    testing their own applications (ex. `-testing` artifacts that some libraries
    expose).
    -   Robolectric shouldn’t need to shadow the library classes.
-   Anticipate developer testing needs specific to the library's use cases.
    -   For example, Room has in-memory testing support.
-   Build tooling concurrent with the library when possible, and with tooling in
    mind otherwise.

### 10. Released using a clearly-defined process

-   Follow Semantic Versioning and pre-release revision guidelines where each
    library moves through alpha, beta, and RC revisions in a timely manner to
    gain feedback and ensure stability.

### 11. Well-documented

-   Provide developers with getting started and use case documentation on
    d.android.com in addition to clear API reference documentation.

### 12. Supported for long-term use

-   Plan for long-term support and maintenance.

### 13. Examples of modern development

-   Where possible, targeting the latest languages, OS features, and tools. All
    new libraries should be written in Kotlin, compile using the latest stable
    Android SDK, and assume that clients are using the latest stable versions of
    Android Studio, Gradle, and AGP. See the
    [AndroidX API Guidelines](/docs/api_guidelines/index.md#dependencies-kotlin)
    for more details, including the use of Java sources and `-ktx` artifacts.

### 14. High quality APIs and ownership

-   All Jetpack libraries are expected to abide by Android and Jetpack API
    Guidelines.

## Target Audience

Jetpack libraries are used by a wide variety of external developers, from
individuals working on their first Android app to huge corporations developing
large-scale production apps. Generally, however, Jetpack libraries are designed
to focus on small- to medium-sized app development teams.

In cases where Jetpack Working Group determines that a library targets a niche
set of apps, the library owner may be asked to justify a significant business
need for the problem being addressed.