Developer guide

Prerequisites

Developing on Replicant isn't much harder than developing on any other free software project as it doesn't require specific knowledge. In fact, you'll probably learn a lot along the way regarding how hardware works, how the Android system is composed, how the kernel works, etc, but you don't need to know all of this to start. However a basic set of skills is required, among which:

If you think you can cope with the requirements, then developing on Replicant should cause you no particular issue.

Notes on writing free software replacements

Writing free software replacements for non-free components may require more skills depending on what you're trying to achieve, though there may be people with the adequate knowledge to help you and from whom you will likely learn a lot.

The porting guides provide instructions for porting a new device to Replicant.

Have a look at the Tasks page and feel free to ask around for help to get started.

Code hosting and submitting patches

Replicant's source code is hosted at git.replicant.us. If you plan to regularly contribute to Replicant and if you don't yet have a code hosting provider that satisfies your needs, you are welcome to host your Replicant-related projects there under your own username, You only need to contact one of Replicant's developers and ask for an account. Please include in your request the name, username and Email address that should be used for creating your account.

Replicant currently doesn't accept merge requests. There are two ways to get your patches included: You can either send them to the mailing list or open an issue on the issue tracker and attach the patches to the issue. Replicant developers will then review your changes.

See the Git documentation for creating a patch. Patches can be send with git send-email. If it's too much hassle for you to set up git send-email, sending the patches with your favorite mail client should be fine, too.

Repositories

When working with Replicant repos, make sure to avoid breaking things. For instance, if you push a commit introducing a compilation error, it will break the whole build process.
It is better to create separate branches (that are not used by the official manifest branches) when your work is still in progress.
Creating branches that add debug infos on a particular topic is usually a good idea since it will save you time next time you want to debug the same component.

LineageMirror details the setup of the LineageOS mirror. Below are the instructions for repos in the Replicant group.

When creating a repository

In order to keep repo naming consistent, please name repositories by their name on the tree, replacing the / by _.
For instance, when forking the LineageOS repo: android_device_samsung_crespo, rename it to device_samsung_crespo on the Replicant repos.
This creates a more consistent way of naming repositories and makes it easier when pushing: just look at the location in the source tree and replace / by _.

When creating a branch

Official Replicant branches are named the following way:

Such as: replicant-2.3 This should be used on the projects repositories as well as the manifest repository.
Any other branch should be considered as Work In Progress (WIP) and thus not be part of any official branch of the manifest.

There is although one exception, with the master branch, that can be used by any project and be in any manifest given that the code held in the master branch will work on any Replicant version.

Upstreaming work

It is generally a good idea to send some changes back to upstream, assuming that they will benefit from it as well.

When it is about the replacement of a non-free component present in the upstream systems, make sure that your replacement is reliable and complete.
Contact the interested developers on the upstream projects before attempting to send your replacement.

LineageOS

The LineageOS team uses Gerrit to manage patch submissions. The process to get your patch included in LineageOS repos is explained on their wiki: Gerrit

You can also push directly using git using the following scheme (untested):

git push ssh://<sshusername>@review.lineageos.org:29418/LineageOS/<projectname> HEAD:refs/for/<branchname>

AOSP

The Android Open Source Project uses Gerrit to manage patch submissions. Some information about submitting patches to AOSP is available: https://source.android.com/source/submit-patches.html

You can push to AOSP's review using:

git push https://android-review.googlesource.com/platform/system/core HEAD:refs/for/master

Writing free software replacements

Here are some tips that may help you achieving a free software replacement for a specific component (some may be more or less relevant regarding the nature of what the component does):

Wiki guidelines

In order the keep the wiki simple and consistent, a few guidelines must be followed when editing.

Regarding the content: Regarding the writing style: Regarding the naming of pages: Regarding the naming of devices:

Commonly-used terminology

In order to keep everything clear and consistent, we use the following terms with a precise meaning in mind:

New images release

  1. Modify the changelog in the vendor files:
    cd path/to/replicant-6.0/vendor/replicant
    edit CHANGELOG.mkdn
    git add CHANGELOG.mkdn
    git commit -sS -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/vendor_replicant.git replicant-6.0
    
  2. Increment the release in the release scripts:
    cd path/to/release-scripts
    edit releasevars.sh
    git add releasevars.sh
    git commit -sS -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/release-scripts.git replicant-6.0
    
  3. Tag all the repositories with the release tag script:
    path/to/release-scripts/releasetag.sh path/to/replicant-6.0
    
  4. In the manifest repo, merge the replicant-6.0-dev branch into the replicant-6.0 branch and increment the release in the manifest:
    cd path/to/manifest
    git checkout replicant-6.0
    git merge replicant-6.0-dev
    edit default.xml
    git add default.xml
    git commit -sS -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/manifest.git replicant-6.0
    
  5. Tag the manifest:
    git tag -u 5816A24C10757FC4 replicant-6.0-0001 -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/manifest.git replicant-6.0-0001
    
  6. Verify all tags:
    cd .repo/manifests
    git verify-tag $(git describe)
    cd ../..
    repo forall -c ' { echo "Verifying $REPO_PROJECT" && git verify-tag $(git describe) 2>/dev/null; } || echo "Error: verification failed!" '
    
  7. Update prebuilts and start the build (in a newly opened shell with the Replicant keys and certificates installed):
    path/to/release-scripts/releasebuild.sh path/to/replicant-6.0
    
  8. Release the images with the release script:
    rm -rf path/to/images/replicant-6.0/0001
    mkdir -p path/to/images/replicant-6.0/0001
    path/to/release-scripts/release.sh path/to/replicant-6.0 path/to/images/replicant-6.0/0001
    
  9. Sign the binaries with the release script:
    path/to/release-scripts/release.sh path/to/replicant-6.0 path/to/images/replicant-6.0/0001 signatures
    
  10. Compress the release files
    cd path/to/images/replicant-6.0
    tar -cjf 0001.tar.bz2 0001
    
  11. Upload the release to OSUOSL:
    rsync -P -4 -ze ssh 0001.tar.bz2 replicant@ftp-osl.osuosl.org:/home/replicant/data/images/replicant-6.0/
    
  12. Unpack the release on OSUOSL, ensure permissions are correct
  13. Update ReplicantImages with the release
  14. Update each device's page with the release
  15. Update ReplicantStatus with the latest status
  16. Verify if other wiki pages need to be updated due to changes introduced by the release (e.g. build pages or ToolsInstallation)
  17. Announce the release on the blog
  18. Update the release on the website and IRC topic

New device documentation

1. Create the device main page, following the naming guidelines applied to other devices (e.g. the Samsung Galaxy S II GT-I9100 is called Galaxy S 2 (I9100) and its page is GalaxyS2I9100)
2. Create all the related sub-pages (build guide, install guide and firmwares list at least), following the naming guidelines applied to other devices (e.g. GalaxyS2I9100Build, GalaxyS2I9100Installation and GalaxyS2I9100Firmwares)
3. Link the sub-pages to the main page in the index
4. Update the ReplicantStatus page of the wiki with the current status of the device
5. Modify the Index page of the wiki and add the new device in the following sections:

6. Add new issues categories to the Replicant project Redmine