Launchpad Code Submission Guidelines

This resource is intended to help beginning developers submit code to Agasti project branches.

This guide assumes you have already discovered how to make your own local branch using bazaar and are now ready to share your changes back to a main project branch.

The first step on the road to code submission is getting your branch back up to speed.

Let's assume you created a local branch long ago called myBranch using:

bzr branch lp:sahana-agasti/mayon myBranch
cd myBranch/

From this point forward we'll assume you're in your local branch's root directory as above.

After many hours of development, you've created a great new feature and are ready to submit. So, what should you do? Well, it's easy to forget, but you should first commit your local changes (don't forget to add a meaningful commit message!)

bzr commit -m "I added a great new feature to index.php that makes waffles in the morning, and adds a menu item to the global template for waffle making."

Now that you've committed, you can merge in changes from your parent branch. Do you see above, how I created this branch from lp:sahana-agasti/mayon? Well, we'll want to use that branch to get any updates that have happened there since we last merged changes.

A conflict is what bzr reports to you if you and someone else have worked on the same file at the same time. The folks over at Canonical, those responsible for both Ubuntu and Launchpad, have written a great article about conflicts in the bazaar vcs.

Bzr doesn't try to make any assumptions about how conflicts should be resolved, rather it just reports the conflicts back and expects you to deal with them. If you read the conflicts guide above, you'll see that bzr has many different types of conflicts. Unfortunately, conflict handling is slightly beyond the scope of this document. There are many ways to deal with conflicts and you are encouraged to find one that works for you. Feel free to take a look at some of the resources below, which all have good suggestions.

• Stuart Colville's Great Guide on Text Conflicts
• How to use your own tools for merging conflicts
• How to RESOLVE conflicts

Oh, and while you're at it, we wholly recommend using Meld for your visual diffs. You can find it in most Linux distribution repositories and on our Mayon Developer's Live Disc.

bzr resolve my/conflicting/file.php

Now that you've resolved those files, you should commit locally again. We recommend you commit immediately before and after merges so-that it's easier to track problems introduced during merge operations vs. those due to programming issues beforehand.

As before, committing is a simple-enough endeavor.

bzr commit -m "Merged in changes from r123 of lp:sahana-agasti/mayon"

Note: it's important to note the revision number of the source of your changes in your commit message as well as the parent branch. While bzr does track these things somewhat on its own, it's nice to have them in commit messages.

This is perhaps the easiest step of the whole process. After you submit a merge request via your merge directive, please stick around! Hang out on IRC with us on IRC or by e-mail and be ready to answer questions about your directive. If you've created a module, pay attention to any security alerts that may arise around your new submission. It's very difficult for maintainers to justify merging code from someone who's unwilling to discuss it.

We also ask that you please be patient regarding your submission. We have some very smart maintainers, but unfortunately, sometimes they're just a little overtaxed and it can take some time for code to make it into the tree. While you're waiting, it would be a great time to make a wiki page about your new submission.

The Agasti community encourages ongoing relationships with our contributors and we're excited to have you aboard.