1# Jetpack Principles
2
3[TOC]
4
5## Ethos of Jetpack
6
7To create components, tools, and guidance that makes it quick and easy to build
8great Android apps, including contributions from Google and the open-source
9community.
10
11## Core Principles of a Jetpack Library
12
13Jetpack libraries provide the following guarantees to Android Developers:
14
15_formatted as “Jetpack libraries are…” with sub-points “Libraries should…”_
16
17### 1. Optimized for external client adoption
18
19-   Libraries should work for first-party clients and may even have optional
20    modules tailored specifically to first-party needs, but primary
21    functionality should target external developers.
22-   Measure success by 3p client adoption, followed by 1p client adoption.
23
24### 2. Designed to satisfy real-world use cases
25
26-   Meet developers where they are and solve the problems that they have
27    building apps -- not designed to just provide parity with existing platform
28    APIs and features
29-   Expose modules that are tightly-scoped to **developer pain points**
30    -   Smaller building blocks for external developers by scoping disjoint use
31        cases that are likely not to co-exist in a single app to individual
32        modules.
33-   Implement layered complexity, with **simple top-level APIs**
34    -   Complicated use case support must not be at the expense of increasing
35        API complexity for the most common simpler use cases.
36-   Have **backing data or a researched hypothesis** (research, demand etc) to
37    prove the library is necessary and sufficient.
38-   Include only functionality that is relevant to the library's stated use case
39    -   End user and developer trust depend on libraries being transparent about
40        their operation. See
41        [Functionality](/docs/api_guidelines#functionality) in
42        the API Guidelines for details.
43
44### 3. Aware of the existing developer ecosystem
45
46-   Avoid reinventing the wheel -- do not create a new library where one already
47    exists that is accepted by the community as a best practice
48
49### 4. Consistent with the rest of Jetpack
50
51-   Ensure that concepts learned in one component can be seen and understood in
52    other components
53-   Leverage Jetpack and community standards, for example:
54    -   For async work, uses Kotlin coroutines and/or Kotlin flow
55    -   For data persistence, uses Jetpack DataStore for simple and small data
56        and uses Room for more complicated Data
57
58### 5. Developed as open-source and compatible with AOSP Android
59
60-   Expose a unified developer-facing API surface across the Android ecosystem
61-   Develop in AOSP to provide visibility into new features and bug fixes and
62    encourage external participation
63-   Avoid proprietary services or closed-source libraries for core
64    functionality, and instead provide integration points that allow a developer
65    to choose between a variety of services as the backing implementation
66-   Comply with AndroidX checks and policies such as API tracking and style
67    checks
68-   See
69    [Integrating proprietary components](/docs/open_source.md)
70    for guidance on using closed-source and proprietary libraries and services
71
72### 6. Written using language-idiomatic APIs
73
74-   Write APIs that feel natural for clients using both
75    [Kotlin](https://developer.android.com/kotlin/interop) and Java
76
77### 7. Compatible with a broad range of API levels
78
79-   Support older platforms and API levels according to client needs
80-   Provide continued maintenance to ensure compatibility with newer platforms
81-   Design with the expectation that every Jetpack API is **write-once,
82    run-everywhere** for Android with graceful degradation where necessary
83
84### 8. Integrated with best practices
85
86-   Guide developers toward using existing Jetpack best-practice libraries,
87    including Architecture Components
88-   Libraries that involve user interfaces, e.g. any reference to `View`
89    classes, must provide non-`View` functional parity when used with the
90    Compose UI toolkit
91
92### 9. Designed for tooling and testability
93
94-   Write adequate unit and integration tests for the library itself
95-   Provide developers with an accompanying testing story for integration
96    testing their own applications (ex. -testing artifacts that some libraries
97    expose)
98    -   Robolectric shouldn’t need to shadow the library classes
99    -   Ex. Room has in-memory testing support
100-   Build tooling concurrent with the library when possible, and with tooling in
101    mind otherwise
102
103### 10. Released using a clearly-defined process
104
105-   Follow Semantic Versioning and pre-release revision guidelines where each
106    library moves through alpha, beta, and RC revisions in a timely manner to
107    gain feedback and ensure stability
108
109### 11. Well-documented
110
111-   Provide developers with getting started and use case documentation on
112    d.android.com in addition to clear API reference documentation
113
114### 12. Supported for long-term use
115
116-   Plan for long-term support and maintenance
117
118### 13. Examples of modern development
119
120-   Where possible, targeting the latest languages, OS features, and tools. All
121    new libraries should be written in Kotlin, compile using the latest stable
122    Android SDK, and assume that clients are using the latest stable versions of
123    Android Studio, Gradle, and AGP. See the
124    [AndroidX API Guidelines](/docs/api_guidelines/index.md#dependencies-kotlin)
125    for more details, including the use of Java sources and `-ktx` artifacts.
126
127### 14. High quality APIs and ownership
128
129-   All Jetpack libraries are expected to abide by Android and Jetpack API
130    Guidelines
131
132## Target Audience
133
134Jetpack libraries are used by a wide variety of external developers, from
135individuals working on their first Android app to huge corporations developing
136large-scale production apps. Generally, however, Jetpack libraries are designed
137to focus on small- to medium-sized app development teams.
138
139-   Note: If the library targets a niche set of apps, the developer pain
140    point(s) addressed by the Jetpack library must be significant enough to
141    justify its need.
142    -   Example : Jetpack Enterprise library
143