AndroidX Core Team | 2e416b2 | 2020-12-03 22:58:07 +0000 | [diff] [blame] | 1 | # Jetpack Principles |
| 2 | |
| 3 | [TOC] |
| 4 | |
| 5 | ## Ethos of Jetpack |
| 6 | |
| 7 | To create components, tools, and guidance that makes it quick and easy to build |
| 8 | great Android apps, including contributions from Google and the open-source |
| 9 | community. |
| 10 | |
| 11 | ## Core Principles of a Jetpack Library |
| 12 | |
| 13 | Jetpack 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 Team | 79a2e7c | 2023-09-26 14:22:02 -0700 | [diff] [blame] | 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 |
Ian Baker | 186108e | 2023-11-20 06:54:36 -0800 | [diff] [blame] | 41 | [Functionality](/docs/api_guidelines#functionality) in |
AndroidX Core Team | 79a2e7c | 2023-09-26 14:22:02 -0700 | [diff] [blame] | 42 | the API Guidelines for details. |
AndroidX Core Team | 2e416b2 | 2020-12-03 22:58:07 +0000 | [diff] [blame] | 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 |
AndroidX Core Team | 2e416b2 | 2020-12-03 22:58:07 +0000 | [diff] [blame] | 61 | - Develop in AOSP to provide visibility into new features and bug fixes and |
| 62 | encourage external participation |
alanv | da56d5d | 2021-02-12 09:00:29 -0800 | [diff] [blame] | 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 |
AndroidX Core Team | 1ef45eba | 2022-10-06 13:08:27 -0700 | [diff] [blame] | 66 | - Comply with AndroidX checks and policies such as API tracking and style |
| 67 | checks |
AndroidX Core Team | 5fa6198 | 2023-01-13 10:43:41 -0500 | [diff] [blame] | 68 | - See |
Ian Baker | 186108e | 2023-11-20 06:54:36 -0800 | [diff] [blame] | 69 | [Integrating proprietary components](/docs/open_source.md) |
AndroidX Core Team | 5fa6198 | 2023-01-13 10:43:41 -0500 | [diff] [blame] | 70 | for guidance on using closed-source and proprietary libraries and services |
AndroidX Core Team | 2e416b2 | 2020-12-03 22:58:07 +0000 | [diff] [blame] | 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 |
AndroidX Core Team | 646aab5 | 2024-03-12 08:31:59 -0700 | [diff] [blame] | 88 | - Libraries that involve user interfaces, e.g. any reference to `View` |
AndroidX Core Team | 8189e06 | 2024-03-12 10:47:30 -0700 | [diff] [blame] | 89 | classes, must provide non-`View` functional parity when used with the |
| 90 | Compose UI toolkit |
AndroidX Core Team | 2e416b2 | 2020-12-03 22:58:07 +0000 | [diff] [blame] | 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 |
AndroidX Core Team | 0b640a8 | 2024-06-04 11:04:30 -0700 | [diff] [blame] | 106 | library moves through alpha, beta, and RC revisions in a timely manner to |
| 107 | gain feedback and ensure stability |
AndroidX Core Team | 2e416b2 | 2020-12-03 22:58:07 +0000 | [diff] [blame] | 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 |
AndroidX Core Team | aebf321 | 2023-03-06 12:42:43 -0800 | [diff] [blame] | 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 |
Ian Baker | 186108e | 2023-11-20 06:54:36 -0800 | [diff] [blame] | 124 | [AndroidX API Guidelines](/docs/api_guidelines/index.md#dependencies-kotlin) |
AndroidX Core Team | aebf321 | 2023-03-06 12:42:43 -0800 | [diff] [blame] | 125 | for more details, including the use of Java sources and `-ktx` artifacts. |
AndroidX Core Team | 2e416b2 | 2020-12-03 22:58:07 +0000 | [diff] [blame] | 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 | |
| 134 | Jetpack libraries are used by a wide variety of external developers, from |
| 135 | individuals working on their first Android app to huge corporations developing |
| 136 | large-scale production apps. Generally, however, Jetpack libraries are designed |
| 137 | to 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 |