BzrWorkflow

Oxide Bzr workflow

Introduction

The Oxide source tree consists of code that is maintained in Bzr, a checkout of Chromium (which is not maintained in Bzr) and a set of patches that are applied to Chromium (which are maintained in Bzr). A script that checks out the correct version of Chromium and automatically applies the Chromium patch set is provided.

The patches stored in Bzr are not directly applied to your local Chromium checkout. Instead, a Mercurial repository is created from Chromium and then the patches are imported in to a Mercurial patch queue, creating a separate working copy. There are a couple of reasons for doing this:

If the patches are applied directly from the files in Bzr without keeping a copy of them, your Chromium checkout will break the next time you update your Oxide branch and another developer has modified any of the patches (you will no longer be able to cleanly unapply the patches from your local Chromium checkout in order to update it).
It provides a fairly simple way to modify patches and create new ones, using a Quilt-like command line interface.
Mercurial is cross-platform, so it is possible for non-Linux users to obtain a source code branch that they can actually work on.

A command line tool is provided to keep the master patch queue (in Bzr) in sync with the Chromium patch queue. This is used automatically when updating your local Chromium branch, but you will need to invoke it manually if you are actually making changes to any patches.

Creating a Mercurial repository is quite extreme - we're open to other suggestions of how to manage the patch queue in a way that makes it easy for developers to work on them, and in a way that is transparent to developers who aren't concerned about these patches.

Getting the code

The trunk branch is located at https://code.launchpad.net/~oxide-developers/oxide/oxide.trunk. Checking out the code is just a matter of running:

bzr branch lp:oxide && cd oxide && python ./client.py

The last step will grab depot tools and then run gclient to check out the revision of Chromium specified in gclient.conf. The checkout is quite large (about 6GB), so it's not recommended to do this on a metered internet connection.

It could take a while depending on the speed of your internet connection, so now might be a good time for you to go and make a cup of tea / coffee or grab some beer.

Once checked out, client.py will automatically apply the Chromium patches from the patches/ directory.

Keeping your local branch up to date

You update your local branch of Oxide in the same way you would for any other Bzr branch, with one additional step - you will need to rerun the client.py script after updating. This will check if your Chromium checkout is up to date, and sync it if necessary. It will also ensure that any changes to the patch set are copied across to your local Chromium checkout.

To update, you can run:

bzr pull && python ./client.py

There is an open bug report to add a bzr hook for automating the last step (see bug 1249143).

If you are working on Chromium patches locally, you will need to make sure that any changes are copied back to Bzr before running client.py (see Making changes to Chromium patches.

Making changes to Chromium patches

Patches are modified using the Mercurial patch queue workflow. After making any changes, please run the following to ensure that these changes are copied back to Bzr, where you can commit as usual:

python ./patch-tool.py sync

You can also do a dry-run, which will output exactly what changes will be made:

python ./patch-tool.py sync -n

Modifying an existing patch

In order to modify an existing patch, you must first make it the current patch. The simplest way to do this is by running (with chromium/src as the current directory):

hg qgoto <patchname>

This will apply the patch (and any before it in the stack) if it is not already applied, and it will unapply patches if it is already applied but not the current patch.

Once you have done this, make the necessary changes to the Chromium source, and then run:

hg qrefresh

Adding a new patch

You add a new patch by running (with chromium/src as the current directory):

hg qnew <patchname>