blob: 7206f45c1a5b2843ec9a2c1b9863d67259fe0235 [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
11You can start contributing to [Room](https://developer.android.com/topic/libraries/architecture/room) and [WorkManager](https://developer.android.com/topic/libraries/architecture/workmanager) from !
12
13Our 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.
14
15## Getting Started
16
17We 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.
18
19### One Time Setup
20
21- Click on the `Actions` tab in the forked `androidx` repository, and enable the use of `Workflows`.
22
23- Download and install JDK 11, if you don’t have it already.
24
25Next, you need to set up the following environment variables:
26
27```bash
28# You could also add this to your .{bash|zsh}rc file.
29export JAVA_HOME="location of JDK 11 folder"
mzgreen42e3a6a2020-07-25 20:57:09 +053030export ANDROID_SDK_ROOT="location of the Android SDK folder"
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070031```
32
33### Checkout & Importing a Project
34
35The list of folders that can be contributed to, using the repository are:
36
37```
38androidx
39-- room
40-- work
41```
42
43**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-master-dev:README.md).
44
45Fork the [AndroidX/androidx](https://.com/AndroidX/androidx) repository.
46
Aurimas4b939852020-07-23 23:57:49 +000047We recommend cloning using blob filter to reduce checkout size:
48```bash
49git clone --filter=blob:none https://.com/YOUR_USERNAME/androidx.git
50```
51
Rahul Ravikumar10efcea2020-07-16 15:52:37 -070052Let’s assume that you want to make a contribution to Room. The first step is to launch Android Studio and import the Room project.
53
54First launch Android Studio using:
55
56```bash
57cd androidx/room
58# This will automatically launch the `room` project in Android Studio.
59./gradlew studio
60```
61
62The studio task automatically downloads the correct version of Android Studio that matches the Android Gradle Plugin version.
63
64### Making Changes
65
66You 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.
67
68### Validating changes locally
69
70Before 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.
71
72Apart from this, there are checks that ensure developers follow the Android coding standards & guidelines.
73
74To make sure that your code passes all the above checks & tests you can run:
75
76```bash
77# Switch to the `room` directory or the project you are working on.
78cd room
79# Run device side and host side tests
80./gradlew test connectedCheck
81
82# Run additional checks
83./gradlew buildOnServer
84
85# If you are testing on an emulator, you can disable benchmark tests as
86# follows since they require a real device to run
87./gradlew \
88test connectedCheck \
89-x :room:room-benchmark:cC \
90-x :room:integration-tests:room-incremental-annotation-processing:test
91```
92
93Once your changes look good, you can push them to your fork of the repository. Now you are ready to make a pull request.
94
95**Note:** When you make changes to an API, you need to run:
96
97```
98./gradlew updateApi
99```
100
101If you are adding new APIs, then you might **additionally need to update** [LibraryVersions.kt](https://.com/AndroidX/androidx/blob/androidx-master-dev/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.
102
103This helps the AndroidX project keep track of API changes and avoid inadvertently adding APIs or introduce backwards incompatible changes.
104
Ahmed El-Helwa82b8132020-08-05 00:19:35 +0000105**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.
106
Rahul Ravikumar10efcea2020-07-16 15:52:37 -0700107**Note: CI build will already check for these but it is best to run them locally to speedup the process.**
108
109### Making a Pull Request
110
111To create a pull request click on [this](https://.com/AndroidX/androidx/pulls) link and then click on New Pull Request.
112
113Then click on the compare across forks and select your forked repository as the HEAD repository. Then click Create.
114
115All pull requests **must follow** the following conventions.
116
1171. The pull request includes a short description of the change, and a longer detailed description.
1182. Include a Test stanza in the pull request which describes the steps followed by the developer to test the changes.
1193. 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.
120
121Here is an example:
122
123```
124Short description for the change.
125
126Longer explanation for the change.
127
128Test: A test stanza. For e.g. /gradlew test connectedCheck
129Fixes: b/<bugId> if applicable
130```
131
132### The Pull Request Workflow
133
134AndroidX is primarily developed in [AOSP](https://android.googlesource.com/platform/frameworks/support/+/androidx-master-dev). 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 .
135
136Here is what a typical pull request workflow looks like:
137
Rahul Ravikumar3dd0bf62020-07-21 17:18:24 -07001381. Create a pull request from **your forked repository** to the androidx-master-dev branch on .
Rahul Ravikumar10efcea2020-07-16 15:52:37 -07001392. Sign the Contributor’s License Agreement at https://cla.developers.google.com/ to get @googlebot to give you the `cla: yes` label.
1403. 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.
1414. Once the changes look good, a Googler will Approve your pull request on .
1425. Your PR will be **tested using workflows**. You can monitor these workflows by using the Actions tab in your forked repository.
1436. 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.
1447. Once **all** the checks in **Gerrit and ** pass, your change will get merged in androidx-master-dev in AOSP and mirrored back to androidx-master-dev in . Congratulations, your change landed in AOSP!
1458. 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.
146
147### Running into problems?
148
149- 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).