keyboard_arrow_left Back to the overview

How to contribute to individual apps

If you would like to contribute to LineageOS, but are unable to set up a development environment, another option is contributing to our individual applications. While these are not the main focus of the project, they are very important, and can always use contributors.

Which apps?

The following apps can be built with Gradle seperate from the main codebase.

App Description Gerrit GitHub
Recorder Audio Recorder Gerrit GitHub
Glimpse Gallery Gerrit GitHub
Aperture Camera Gerrit GitHub
Camelot PDF Viewer Gerrit GitHub
ExactCalculator Calculator Gerrit GitHub
Twelve Music Player Gerrit GitHub
Jelly Browser Gerrit GitHub
LatinIME Keyboard Gerrit Github
Etar Calendar Gerrit GitHub-Upstream

How can I contribute?

Setting up Git

In order to contribute, you will need to install Git on your computer.

Install Git

On Windows

Install Git for Windows.

On macOS

Install Git using the Git installer.

On Linux

You can install Git by running:

sudo apt install git

More specific instructions for different distributions can be found here.

Configure Git

Run:

git config --global user.name "Your Name"
git config --global user.email "youremail@example.com"

Cloning the source code

To begin, navigate to the Gerrit page of the app you would like to work on. From there, clone the source code and the commit hooks, by using the following git command:

git clone "https://github.com/LineageOS/android_packages_apps_<app-name>" && (cd "android_packages_apps_<app-name>" && mkdir -p `git rev-parse --git-dir`/hooks/ && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://review.lineageos.org/tools/hooks/commit-msg && chmod +x `git rev-parse --git-dir`/hooks/commit-msg)

Importing into Android Studio

Once you have cloned the source code, you can import the app into Android Studio.

First make sure you have the latest version of Android Studio installed. It is available here, or as a flatpak, if you prefer.

Once it is downloaded, you can import the project, make your changes, and then save the file. You will be able to build these apps with Gradle, and install them on a device or emulator.

Uploading your changes

Once you are satisfied with your changes, navigate to the folder of your app in the terminal and run:

git add .
git commit

An editor will pop up. In the first line, type a short (less than 50 characters) description of your changes, then put a blank line, and, if you want, a more detailed description of your changes. Make sure to preface the title of the commit with the app you are working on.

LineageOS uses Gerrit to review proposed changes. Before you begin, you’ll need to create an account, and configure an SSH key.

After you’ve done this, you can push your commits to Gerrit:

git remote add gerrit ssh://<gerritusername>@review.lineageos.org:29418/LineageOS/android_packages_apps_<app-name>
git push gerrit HEAD:refs/for/main

Getting your submission reviewed/merged

All submitted patches go through a code review process prior to being merged. In addition to peer reviews, certain project members have the capability to merge your changes into LineageOS. To make sure they get informed:

1) Add the “PROJECT-Lineage-apps” group as reviwers. (Click on the little person to the right of “reviewers”.)

2) Set the proper labels to indicate your patch is ready.

Editing your submission

If the reviewers point out anything that needs to be fixed, have no fear. You can make the changes, and then run:

git add .
git commit --amend

Your commit message should show up in an editor. You can edit it, or just quit the editor. You can then run git push gerrit HEAD:refs/for/main to upload your changes to Gerrit.

Eventually, when your change looks perfect, someone will approve and merge it. Awesome!

Tips

Modifying strings

When contributing to these apps, keep in mind that modifiying strings differs from normal Android app development.

Adding strings

When an app is imported from AOSP to Lineage, we generally keep the strings separate by adding a string file with the name of either cm_strings or lineage_strings. This is so that we can translate them and keep track of our own strings verus upstream. When editing an app’s strings check to see if the app has one of these files. If it does then all new strings should be added there otherwise you can simply add strings to the regular strings.xml file.

Editing strings

When editing current strings, be sure to only edit the main strings file in values/strings. There is no need to update, add or delete any of the translations, even if you only changed the string name. All of this is taken care of by our translation import.

gradle-generatebp

LineageOS apps use the gradle-generatebp tool. This Gradle plugin automatically generates .bp files (Android Blueprint build files) for imported libraries, allowing developers to choose which dependencies to use from AOSP and which to include as prebuilts.

Usage

./gradlew generateBp should be executed from the app directory whenever you:

The configuration, defined in app/build.gradle.kts, specifies which dependencies are available in AOSP and which should be treated as prebuilts:

configure<GenerateBpPluginExtension> {
    targetSdk.set(android.defaultConfig.targetSdk!!)
    minSdk.set(android.defaultConfig.minSdk!!)
    availableInAOSP.set { module: Module ->
        when {
            module.group.startsWith("androidx") -> {
                // We provide our own androidx.pdf
                !module.group.startsWith("androidx.pdf")
            }
            else -> false
        }
    }
}

This specific configuration would make all modules from the androidx group available in AOSP, except the androidx.pdf group, for which the tool will now import the prebuilt AAR/JARs and create the corresponding .bp rules.

The tool is integrated into the CI system to ensure there’s no mismatch between Gradle dependencies and AOSP dependencies.

Common commands

git

git subcommands

Resources

Git Immersion

Git and repo overview

Gerrit Documentation