We recently moved our infrastructure from our own internal servers to services offered by public servers. This is the status of the migration:
|bugs||work in progress|
|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:
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 <firstname.lastname@example.org>"
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
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" --email@example.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
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.