blob: a57e94026e6b5dbc4bbf6f05fb923526418630fa [file] [log] [blame] [view]
AndroidX Core Team2e416b22020-12-03 22:58:07 +00001# 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.
AndroidX Core Team79a2e7c2023-09-26 14:22:02 -070038- 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
Ian Baker186108e2023-11-20 06:54:36 -080041 [Functionality](/docs/api_guidelines#functionality) in
AndroidX Core Team79a2e7c2023-09-26 14:22:02 -070042 the API Guidelines for details.
AndroidX Core Team2e416b22020-12-03 22:58:07 +000043
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
AndroidX Core Team2e416b22020-12-03 22:58:07 +000061- Develop in AOSP to provide visibility into new features and bug fixes and
62 encourage external participation
alanvda56d5d2021-02-12 09:00:29 -080063- 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
AndroidX Core Team1ef45eba2022-10-06 13:08:27 -070066- Comply with AndroidX checks and policies such as API tracking and style
67 checks
AndroidX Core Team5fa61982023-01-13 10:43:41 -050068- See
Ian Baker186108e2023-11-20 06:54:36 -080069 [Integrating proprietary components](/docs/open_source.md)
AndroidX Core Team5fa61982023-01-13 10:43:41 -050070 for guidance on using closed-source and proprietary libraries and services
AndroidX Core Team2e416b22020-12-03 22:58:07 +000071
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
AndroidX Core Team646aab52024-03-12 08:31:59 -070088- Libraries that involve user interfaces, e.g. any reference to `View`
AndroidX Core Team8189e062024-03-12 10:47:30 -070089 classes, must provide non-`View` functional parity when used with the
90 Compose UI toolkit
AndroidX Core Team2e416b22020-12-03 22:58:07 +000091
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
AndroidX Core Team0b640a82024-06-04 11:04:30 -0700106 library moves through alpha, beta, and RC revisions in a timely manner to
107 gain feedback and ensure stability
AndroidX Core Team2e416b22020-12-03 22:58:07 +0000108
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
AndroidX Core Teamaebf3212023-03-06 12:42:43 -0800121 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
Ian Baker186108e2023-11-20 06:54:36 -0800124 [AndroidX API Guidelines](/docs/api_guidelines/index.md#dependencies-kotlin)
AndroidX Core Teamaebf3212023-03-06 12:42:43 -0800125 for more details, including the use of Java sources and `-ktx` artifacts.
AndroidX Core Team2e416b22020-12-03 22:58:07 +0000126
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