This repo is an official mirror of Android Jetpack libraries that enables external contributions to a select number of libraries via GitHub pull requests.
The 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 GitHub 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.
You can start contributing to any of the following library groups from GitHub:
Not sure where to start? Take a look at the official feature/bug bounty list.
Our 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.
We have tried to make contributing to androidx a lot easier with this new setup. Just start by creating a fork of the androidx/androidx GitHub repository.
Click on the Actions tab in the forked androidx repository, and enable the use of Workflows.
Download and install JDK 11, if you don’t have it already.
Note the installation directory. If you already have JDK 11 installed and set as default, you can find this with which javac.
Download and install Android Studio if you don't have it already. Then, locate your Android SDK directory at Tools > SDK Manager > Android SDK Location.
If you already have the SDK installed or don't plan on using Android Studio, just note the SDK directory.
Download and install the NDK. You can either do this using the command-line sdkmanager or from Android Studio using Tools > SDK Manager, checking Show Package Details, and expanding NDK.
sdkmanager --install "ndk;23.1.7779620" sdkmanager --install "cmake;3.22.1" --channel=3 #channel 3 is the canary channel
Next, set up the following environment variables:
# You could also add this to your .{bash|zsh}rc file. export JAVA_HOME="location of JDK 11 directory" export ANDROID_SDK_ROOT="location of the Android SDK directory"
The list of folders that can be contributed to, using the GitHub repository are:
androidx -- activity -- appcompat -- biometric -- compose/compiler -- compose/runtime -- core -- datastore -- fragment -- lifecycle -- navigation -- paging -- room -- work
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.
Fork the androidx/androidx repository.
We recommend cloning using blob filter to reduce checkout size:
git clone https://github.com/YOUR_USERNAME/androidx.git
NOTE: If you are low on disk space, then you can use the following command to save some space in your checkout. :point_left:
# Filters any blob > 10M git clone --filter=blob:limit=10M https://github.com/YOUR_USERNAME/androidx.git
Let’s assume that you want to make a contribution to Room. The first step is to launch Android Studio and import the Room project.
First launch Android Studio using:
cd androidx/room # This will automatically launch the `room` project in Android Studio. ./gradlew studio
The studio task automatically downloads the correct version of Android Studio that matches the Android Gradle Plugin version.
You 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 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.
Before 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.
Apart from this, there are checks that ensure developers follow the Android coding standards & guidelines.
To make sure that your code passes all the above checks & tests you can run:
# Switch to the `room` directory or the project you are working on. cd room # Run device side and host side tests ./gradlew test connectedCheck # Run additional checks ./gradlew buildOnServer # If you are testing on an emulator, you can disable benchmark tests as # follows since they require a real device to run ./gradlew \ test connectedCheck \ -x :room:room-benchmark:cC \ -x :room:integration-tests:room-incremental-annotation-processing:test
Once your changes look good, you can push them to your fork of the repository. Now you are ready to make a pull request.
Note: When you make changes to an API, you need to run:
./gradlew updateApi
If you are adding new APIs, then you might additionally need to update 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.
This helps the AndroidX project keep track of API changes and avoid inadvertently adding APIs or introduce backwards incompatible changes.
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.
Note: CI build will already check for these but it is best to run them locally to speedup the process.
To create a pull request click on this link and then click on New Pull Request.
Then click on the compare across forks and select your forked repository as the HEAD repository. Then click Create.
All pull requests must follow the following conventions.
Here is an example:
Short description for the change. Longer explanation for the change. Test: A test stanza. For e.g. /gradlew test connectedCheck Fixes: b/<bugId> if applicable
AndroidX is primarily developed in AOSP. This flow simply mirrors pull requests from GitHub 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 GitHub.
Here is what a typical pull request workflow looks like:
cla: yes label.import/copybara left by @copybara-service, by clicking details.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.