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.

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

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:

• Update existing dependencies
• Add new dependencies
• Make changes that affect the build configuration

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 add <file name> to stage a file that has been changed or added.

• git commit -m "comment" to commit a change.

• git reset HEAD <file name> to unstage a file.

• git revert HEAD to undo the last commit.

• git status to see the status of a project.

git subcommands

• --date="DATE" to specify the date of change if necessary. DATE has to be in RFC 2822, ISO 8601 or git internal time format.

  Examples:

  • RFC 2822: Wed, 17 Jan 2018 17:39:48 +0100

  • ISO 8601: 2018-01-17T17:39:48+0100

  • git internal format: 1516210788 +0100

• --author="NAME <EMAIL>" to name the author if you did not write the patch yourself.

• --amend to modify the last commit.

Resources

Git Immersion

Git and repo overview

Gerrit Documentation