Developer’s Guide

Foreword

We recently moved our infrastructure from our own internal servers to services offered by public servers. This is the status of the migration:

service status
website migrated
bugs work in progress
forums migrated
continuous integration planned (offline)
mailing lists won’t migrate

Before you begin

Please make sure you are familiar with Task Based Development and Bazaar.

Communication is key!

Please keep in mind that your time will be wasted if you and someone else are working on the same issue without you not knowing about the other person and vice-versa. In order to avoid this situation, we need to communicate.

There are several other inneficiencies not discussed here that can be avoided thru a very simple expedient: keep people informed about what you are doing. The software management platform made available by Launchpad helps a lot! But most situations can be addressed by simply sending an email to our mailing list.

If you are a sporadic contributor and you are willing to keep things simple, please simply send and email to our mailing list.

Launchpad or not Launchpad: that’s the question

If you are a sporadic contributor or willing to keep things deadly simple, the answer is NO. In this case, simply jump to the next topic.

Otherwise, please consider spending some time getting acquainted to the workflow provided by Launchpad. Below you see a selection of links which explain the most critical points for beginners:

Bazaar Tutorial

This is a quick guide on the most common Bazaar commands. We also cover essential aspects of the workflow provided by Launchpad.

If you are looking for more sources of information:

First baby steps

Please install essential Bazaar packages onto your Linux box:

$ apt-get install bzr bzr-email xdg-utils xz-utils

You may also find useful to install graphical tools:

$ apt-get install qbzr

Now you need to tell who you are to Bazaar. For example:

$ bzr whoami "Richard Gomes <rgomes.info@gmail.com>"

Tip

Optional but highly recommended: Open an account with Launchpad so that you will take advantage of the workflow. In particular, being registered, you will be able to assign an issue to yourself before starting working. This is important to make others aware about what you are doing.

Obtaining the code

The first thing consists on cloning the repository onto your local machine:

$ mkdir -p ~/workspace/jquantlib
$ cd ~/workspace/jquantlib
$ bzr branch lp:jquantlib trunk

The name trunk is intentional here: it means that you’ve obtained the branch called trunk from the repository. For Git users, it would be equivalent to master.

Working on a feature branch

Our issue management system at http://bugs.jquantlib.org contains the list of issues we are working on. You should be assigning the issue you are working on to yourself. Alternatively, you should be making people aware about what you are doing by sending a note to our mailing list.

Let’s suppose you will be working on issues #200, #201 and #202, which are related to interpolations. A good name for this task would be interpolation-fixes. Create a feature branch like this:

$ cd ~/workspace/jquantlib
$ bzr branch trunk interpolation-fixes

Tip

See our notes on stacked branches if you are interested on saving time and disk space.

Now you are going to work on your feature branch. Simply cd to its directory:

$ cd interpolation-fixes

Suppose that you’ve worked on some files. Let’s see what happened:

$ bzr status
added:
  .jquantlib/src/main/java/org/jquantlib/math/interpolations/LinearInterpolationFactory.java
  .jquantlib/src/test/java/org/jquantlib/math/interpolations/LinearInterpolationFactoryTest.java
modified:
  .jquantlib/src/main/java/org/jquantlib/math/interpolations/LinearInterpolation.java

Commiting your changes

Suppose you are happy with your changes. In other words:

  • you’ve added test cases
  • you’ve run the full bloody test suite
  • all tests pass

You can now save your changes on the source control:

$ bzr commit -m "Issues #200, #201 and #202 fixed. All tests pass."

Submiting your patch via email

When you feel your implementation is complete, it’s time to submit it to the maintainer:

$ cd ~/workspace/jquantlib
$ cd interpolation-fixes
$ bzr send --message="Fixing #200, #201 and #202" --mail-to=rgomes.info@gmail.com

When your patch is several megabytes in size

Please compact your patch before sending via email:

$ cd ~/workspace/jquantlib
$ cd interpolation-fixes
#-- create a merge request
$ bzr send -o ../interpolation-fixes.patch
#-- compact the .patch file onto a .patch.tar.xz file
$ cd ~/workspace/jquantlib
$ tar cJf interpolation-fixes.patch.tar.xz interpolation-fixes.patch

Submitting your patch via Launchpad

As an alternative to submitting your branch via e-mail, you can also publish your feature branch to the server where it can be cloned over HTTP for others to use, as well as for review and merging by the package maintainer. Let’s assume that you want to publish your interpolation-fixes branch in hopes of landing it in the next release. Let’s also assume that you have an account on Launchpad, and want to publish your branch there. It works like this:

$ bzr launchpad-login myusername
$ bzr push lp:~myusername/jquantlib/interpolation-fixes

where myusername is your account with Launchpad.

After pushing your branch, you can include its URL in an e-mail you send to the maintainer, requesting a merge of your branch. You can also link your branch to an issue maintained by Launchpad’s issue management system or even using Launchpad’s merge request feature to alert the maintainer(s) that your branch is ready to merge. See: https://dev.launchpad.net/UsingMergeProposals

Notes

Where I can find tutorials on Bazaar and Launchpad?

Launchpad channel on You Tube

How do I manage large projects?

When a project has thousands of files or too much history, we’d better consider stacked branches.

In a nutshell, a stacked branch is backed by some other branch, i.e: only your changes after the branch was taken are stored in your stacked branch; all previous changes and history are kept in the original branch which backs the stacked branch.

You might be confused at this point because the explanation above does not add anything different to what a branch is. You are correct: conceptually, a stacked branch works exactly as any other branch. The difference is how information is stored in the file system: the directory which contains your stacked branch contains only your most recent changes and history; all existing changes and histories are not copied when you create a stacked branch.

This is an example. The first step consists on creating a regular branch on your local machine, taking it from the server:

#-- branching from the server
$ cd ~/bzr-repositories
$ bzr branch lp:launchpad

Now create your stacked branches:

#-- clone from a regular branch onto a stacked branch
$ cd ~/workspace/jquantlib
$ bzr clone --stacked ~/bzr-repositories/jquantlib/trunk some-cool-feature

Notice that the origin of your stacked branch is a regular branch sitting on your file system, not a remote branch sitting on the server. In other words, if you push your changes, you are pushing onto the regular branch sitting on your file system, not onto the remote branch sitting on the server.