Skip to main content

Development Process

TODO

This article is a work in progress.

Development starts with the creation of a ticket, describing the issue and solution space. Once work on this ticket starts, we expect to see the following artifacts;

  • a topic development branch for the relevant platform_manifest repository,

  • one topic development branch per repository impacted,

  • a topic with any patches submitted for review in Gerrit.

The goal of this article is to outline how developers should work together, on functionality that Apostrophy OS implements, how it is tracked, reviewed, tested, implemented and applied and re-applied moving forward (onto moving and future releases of Android, as well as alternative builds).

Ideally, we have;

  • self-contained patches against one or more repositories (i.e. one per repository),

  • that are recognizable in and by themselves (i.e. ticket numbers in their names), and

  • that can be applied, or re-applied, or omitted individually (as sets), independently from other (sets of) patches.

Choose a Strategy​

Our manifests do not lock in repositories to particular revisions, but instead follow HEAD for branches. This implies that for the duration of a topic being under development, the repositories unrelated to the topic being developed, and have thus not been forked off, can (and will) move forward.

Acknowledging that topic development can not chase moving targets, it is recommended to consider following a particular strategy;

Branching off Individual Repositories​

Consider using a strategy branching off individual repositories as you go, taking in to account;

  • Not too many repositories are impacted, or impact the topic at hand should they change.
  • The development probably doesn't take a significant period of time.

Choosing a Global Branch-off Point​

For longer-running development projects and/or rich dependency trees, consider choosing a global branch-off point;

  • Chooses a stable release tagged in all repositories, or tags all repositories to mark the branch-off point.

  • Executes topic development from said branch-off points, and makes merging or rebasing an exercise for the later "review" stage of the process.

Branch, Code, Commit & Submit​

The process of coding in changes is a natural process, and of course you don't really want to commit and submit for review, a sloppy work-in-progress series of commits (that include superfluous log messages, maybe some logical mistakes, summary skill issues, etc.).

Step 1: Branch off Individual Repositories​

We start work by branching off a repository:

$ repo start <topic-branch-name> <path/to/repository/>

meaning, for example ticket T1785 (Re-implement Ledger functionality);

$ repo start dev/T1785 aphy/aos/
This is not the only repository that is going to need to be forked

Now, we edit aphy/aos/aos.mk and eject the PRODUCT_PACKAGES += AphyLauncher and associated lines, and remove associated artifacts. Commit it, push it;

# git -C aphy/aos/ push <remote> HEAD:refs/heads/<topic-branch-name>
$ git -C aphy/aos/ push mc02 HEAD:refs/heads/dev/T1785
Force Pushes are (should be) permitted for dev/ branches

The effective change here is that the inclusion of AphyLauncher no longer overrides the inclusion of packages/apps/Launcher3 (if that just so happened to be already there, otherwise see Step 3).

Step 2: A New Repository?​

Considering we are forking a graphene/ repository, we should establish an aphy/ repository. But creating such repository is a privileged action, and can not be performed by individual developers.

It is addressed during the review stage of the development process. For now, we can just make a mental note about it.

Step 3: Change the Platform Manifest​

In order to allow your colleagues and fellow enthusiasts to participate in the endeavour, provide them with a topic development version of the platform manifest.

$ cd $APHY_ROOT/src/aphyos/aphy/platform_manifest
$ git checkout -b dev/T1785
# Edit default.xml to reflect the new source locations and branches for the packages impacted
$ git commit default.xml -m "dev/T1785"
$ git push origin dev/T1785

Step 4: Synchronize Release Build Hierarchy​

$ cd $APHY_ROOT/build/
$ repo init -u ssh://gerrit.aphy.ag/mc02/platform_manifest -b dev/T1785
$ repo sync -j8

For internal system packages, you can edit source code in your build hierarchy directly, build and test the changes.

For external system packages,

Step 5: Code, Share, Review, Release​

Do your work in isolation, or as part of a team, where your work is integrated and shared with colleagues for testing and feedback, through the aforementioned topic development branches and repository manifest changes. It is easy, cheap and essential.

The Review stage is a submission of your topic development work to topic development branches in the related source code repositories (we address the constraints of needing sudden forks while working separately).

External System Packages​

This section concerns the system packages that are built external to the release build process, meaning the source code hierarchy for the system package lives outside of the release build hierarchies, and the release build hierarchy includes one or more APK files.

We would seek to include either one of two system package build variants, namely the release APK for the user release build variant, and the debug APK for the userdebug release build variant, with something similar to the snippet shown here;

(...)
ifneq ($(filter $(TARGET_BUILD_VARIANT),eng userdebug),)
LOCAL_SRC_FILES := $(LOCAL_MODULE)-userdebug.apk
else
LOCAL_SRC_FILES := $(LOCAL_MODULE)-user.apk
endif
(...)

Internal System Packages​

Certain system packages are built internally to the release build process, in order to resolve accesses to privileged APIs, and/or be signed with platform keys.