blob: 82015f19f6759c99895ebf96ac351e6ef39775bf [file] [log] [blame] [view]
Rahul Ravikumar10efcea2020-07-16 15:52:37 -07001## Introduction
2
3This repo is an official mirror of Android Jetpack libraries that enables external contributions to a select number of libraries via pull requests.
4
5### Why this repository exists
6
7The Android team has been exploring how we could make it easier to develop libraries that don’t rely on infrastructure from the Android Open Source Project (AOSP). This infrastructure has two benefits. First, it makes it easier to contribute to a small set of Jetpack libraries. Second, this parallel infrastructure makes it possible to build and test Jetpack libraries against non-Android target platforms.
8
9### What can you contribute to?
10
Dustin Lamd6009c32020-08-13 11:51:05 -070011You can start contributing to any of the following library groups from :
Dustin Lameec21a42020-10-13 15:12:26 -070012- [Activity](https://developer.android.com/guide/components/activities/intro-activities)
Dustin Lam7c04f762020-12-11 17:36:12 -080013- [Biometric](https://developer.android.com/training/sign-in/biometric-auth)
Dustin Lamc93a99d2020-12-31 00:08:18 +000014- [Compose Compiler](https://developer.android.com/jetpack/androidx/releases/compose-compiler)
Dustin Lameec21a42020-10-13 15:12:26 -070015- [Fragment](https://developer.android.com/guide/components/fragments)
Dustin Lam841bb082020-12-17 18:13:34 +000016- [Lifecycle](https://developer.android.com/topic/libraries/architecture/lifecycle)
Dustin Lameec21a42020-10-13 15:12:26 -070017- [Navigation](https://developer.android.com/guide/navigation)
Dustin Lamd6009c32020-08-13 11:51:05 -070018- [Paging](https://developer.android.com/topic/libraries/architecture/paging)
19- [Room](https://developer.android.com/topic/libraries/architecture/room)
20- [WorkManager](https://developer.android.com/topic/libraries/architecture/workmanager)
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070021
Rahul Ravikumar8f1880f2020-08-25 11:39:24 -070022Not sure where to start? Take a look at the official [feature/bug bounty list](http://goo.gle/androidx-bug-bounty).
23
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070024Our tooling currently supports **macOS and Linux**. This new setup is a **work-in-progress**, so it might have some rough edges. Please bear with us while we streamline this workflow.
25
26## Getting Started
27
Frieder Bluemle07c59542020-10-28 23:24:13 -070028We have tried to make contributing to androidx a lot easier with this new setup. Just start by creating a fork of the [androidx/androidx](https://.com/androidx/androidx) repository.
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070029
30### One Time Setup
31
32- Click on the `Actions` tab in the forked `androidx` repository, and enable the use of `Workflows`.
33
34- Download and install JDK 11, if you don’t have it already.
35
36Next, you need to set up the following environment variables:
37
38```bash
39# You could also add this to your .{bash|zsh}rc file.
40export JAVA_HOME="location of JDK 11 folder"
mzgreen42e3a6a2020-07-25 20:57:09 +053041export ANDROID_SDK_ROOT="location of the Android SDK folder"
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070042```
43
44### Checkout & Importing a Project
45
46The list of folders that can be contributed to, using the repository are:
47
48```
49androidx
Simon Schillere1e83c62020-10-14 09:59:07 -070050-- activity
Dustin Lam7c04f762020-12-11 17:36:12 -080051-- biometric
Dustin Lamc93a99d2020-12-31 00:08:18 +000052-- compose/compiler
Simon Schillere1e83c62020-10-14 09:59:07 -070053-- fragment
Dustin Lam841bb082020-12-17 18:13:34 +000054-- lifecycle
Simon Schillere1e83c62020-10-14 09:59:07 -070055-- navigation
Dustin Lamd6009c32020-08-13 11:51:05 -070056-- paging
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070057-- room
58-- work
59```
60
Alan Viverette053e7e62020-12-15 10:22:06 -050061**Note:** For other projects, you will still need to use the Gerrit workflow used by the Android Open Source Project (AOSP). For more information, please look at the [README](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:README.md).
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070062
Frieder Bluemle07c59542020-10-28 23:24:13 -070063Fork the [androidx/androidx](https://.com/androidx/androidx) repository.
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070064
Aurimas4b939852020-07-23 23:57:49 +000065We recommend cloning using blob filter to reduce checkout size:
66```bash
Dustin Lamf66d2aa2020-09-10 19:21:50 -070067git clone https://.com/YOUR_USERNAME/androidx.git
Aurimas4b939852020-07-23 23:57:49 +000068```
69
Rahul Ravikumare6857b32020-10-15 22:13:38 +000070---
71
72> NOTE: If you are low on disk space, then you can use the following command to save some space in your checkout. :point_left:
73
74```bash
75# Filters any blob > 10M
76git clone --filter=blob:limit=10M https://.com/YOUR_USERNAME/androidx.git
77```
78---
79
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070080Let’s assume that you want to make a contribution to Room. The first step is to launch Android Studio and import the Room project.
81
82First launch Android Studio using:
83
84```bash
85cd androidx/room
86# This will automatically launch the `room` project in Android Studio.
87./gradlew studio
88```
89
90The studio task automatically downloads the correct version of Android Studio that matches the Android Gradle Plugin version.
91
92### Making Changes
93
94You can now start making changes to the Room project. Making changes is just like making changes to any other Android project. It’s a good idea to build consensus on the change you intend to make. Make sure there is a related issue on the [AOSP issue tracker](https://issuetracker.google.com/issues/new?component=192731&template=842428) and start a conversation on that issue to ensure project maintainers are aware of it. It is best to start the conversation as early as possible to avoid duplicating work as other contributors might already be working on it.
95
96### Validating changes locally
97
98Before you send out a pull request, it’s always a good idea to run tests locally to make sure that you have not accidentally introduced bugs. Also, given all AndroidX projects follow semantic versioning, it's also important for projects to not introduce breaking changes without changing the library’s major version.
99
100Apart from this, there are checks that ensure developers follow the Android coding standards & guidelines.
101
102To make sure that your code passes all the above checks & tests you can run:
103
104```bash
105# Switch to the `room` directory or the project you are working on.
106cd room
107# Run device side and host side tests
108./gradlew test connectedCheck
109
110# Run additional checks
111./gradlew buildOnServer
112
113# If you are testing on an emulator, you can disable benchmark tests as
114# follows since they require a real device to run
115./gradlew \
116test connectedCheck \
117-x :room:room-benchmark:cC \
118-x :room:integration-tests:room-incremental-annotation-processing:test
119```
120
121Once your changes look good, you can push them to your fork of the repository. Now you are ready to make a pull request.
122
123**Note:** When you make changes to an API, you need to run:
124
125```
126./gradlew updateApi
127```
128
Alan Viverette053e7e62020-12-15 10:22:06 -0500129If you are adding new APIs, then you might **additionally need to update** [LibraryVersions.kt](https://.com/androidx/androidx/blob/androidx-main/buildSrc/src/main/kotlin/androidx/build/LibraryVersions.kt) as well, before running the updateApi task. This is **relevant when the library’s API is frozen** (betas, rc’s and stable versions). For alpha versions, you don’t have to update this file.
Rahul Ravikumar10efcea2020-07-16 15:52:37 -0700130
131This helps the AndroidX project keep track of API changes and avoid inadvertently adding APIs or introduce backwards incompatible changes.
132
Ahmed El-Helwa82b8132020-08-05 00:19:35 +0000133**Note:** In case you make a valid violation of Lint, you can use `@Suppress("Rule")` in Kotlin, or `@SuppressLint("Rule")` in Java to suppress the rule.
134
Rahul Ravikumar10efcea2020-07-16 15:52:37 -0700135**Note: CI build will already check for these but it is best to run them locally to speedup the process.**
136
137### Making a Pull Request
138
Frieder Bluemle07c59542020-10-28 23:24:13 -0700139To create a pull request click on [this](https://.com/androidx/androidx/pulls) link and then click on New Pull Request.
Rahul Ravikumar10efcea2020-07-16 15:52:37 -0700140
141Then click on the compare across forks and select your forked repository as the HEAD repository. Then click Create.
142
143All pull requests **must follow** the following conventions.
144
1451. The pull request includes a short description of the change, and a longer detailed description.
1462. Include a Test stanza in the pull request which describes the steps followed by the developer to test the changes.
1473. Include a Fixes stanza that describes the issue being fixed. That way the corresponding issue trackers can automatically be resolved once the change lands in AOSP.
148
149Here is an example:
150
151```
152Short description for the change.
153
154Longer explanation for the change.
155
156Test: A test stanza. For e.g. /gradlew test connectedCheck
157Fixes: b/<bugId> if applicable
158```
159
160### The Pull Request Workflow
161
Alan Viverette053e7e62020-12-15 10:22:06 -0500162AndroidX is primarily developed in [AOSP](https://android.googlesource.com/platform/frameworks/support/+/androidx-main). This flow simply mirrors pull requests from into Gerrit, For all intents and purposes, AOSP is the **single** **source of truth**, all changes will be merged in Gerrit and mirrored back to .
Rahul Ravikumar10efcea2020-07-16 15:52:37 -0700163
164Here is what a typical pull request workflow looks like:
165
Alan Viverette053e7e62020-12-15 10:22:06 -05001661. Create a pull request from **your forked repository** to the androidx-main branch on .
Rahul Ravikumar10efcea2020-07-16 15:52:37 -07001672. Sign the Contributor’s License Agreement at https://cla.developers.google.com/ to get @googlebot to give you the `cla: yes` label.
1683. Your PR will be reviewed using the pull request flow. You can address the comments / suggestions in your forked repository and update the pull request as normal.
1694. Once the changes look good, a Googler will Approve your pull request on .
1705. Your PR will be **tested using workflows**. You can monitor these workflows by using the Actions tab in your forked repository.
1716. Once your **pull request has been approved** by a Googler, it will also be **mirrored to AOSP Gerrit**. You can find the link to Gerrit under the status check, `import/copybara` left by `@copybara-service`, by clicking details.
Alan Viverette053e7e62020-12-15 10:22:06 -05001727. Once **all** the checks in **Gerrit and ** pass, your change will get merged in androidx-main in AOSP and mirrored back to androidx-main in . Congratulations, your change landed in AOSP!
Rahul Ravikumar10efcea2020-07-16 15:52:37 -07001738. Currently, your pull request will not get automatically closed when your changes are merged. So you will have to close the pull request manually. We are working on improving the workflow to address this.
174
175### Running into problems?
176
177- If you see workflows failing, then look at the verbose logs under the `Actions` tab for more information. If you don’t understand why a test might be failing, then reach out to us by creating a new issue [here](https://issuetracker.google.com/issues/new?component=923725&template=1480355).