Table of Contents
Launchpad Code Submission Guidelines
This resource is intended to help beginning developers submit code to Agasti project branches.
Assumptions
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.
Step 1: Prepare for a Merge
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.
Commit Locally
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."
Step 2: Merge from Parent
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.
bzr merge lp:sahana-agasti/mayon
Deal with Conflicts (Eeep!)
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.
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.
Once you've fixed the conflicted files, you can officially resolve the conflict by issuing the following.
bzr resolve my/conflicting/file.php
Committing Your Local Merge
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.
Step 3: Verify your Patches Still Work!
Now that you've merged in changes from the parent branch, it's best to take a little time to make sure your patches still work. You should:
- Read the log of changes from the merge
- Re-run any tests you have written to verify they still pass
- Perform functional tests whether by automation or manually
- Try a clean build or install with your patches applied
- Visually confirm that everything still works
If anything is broken, you'll need to fix the issues and start all this process again back at Step 1.
Step 4: Do a Documentation Sweep
Okay time to submit… right? Whoah! One second there partner! We need you to do just one more thing. Please check that you've sufficiently documented your code! Remember that this is a volunteer project and our volunteers branch maintainers have to read everything you submit before they can merge it into the trunk. Please take a moment to make sure your code is documented enough that a complete stranger can understand what's going on and that it will work with our Doxygen service.
Step 5: Generate a Merge Directive
- Code? Written!
- Changes? Merged!
- Conflicts: Resolved!
- Documentation: Herman Melville would be jealous!
Well, then, it sounds like you're ready to generate your merge directive!
Bzr offers us many ways to generate merge directives and Launchpad even offers a few more beyond that. To keep things simple, however, the Agasti project branch maintainers request that you generate merge directive files (which are really just very special diff packages). These are easy to generate using the bzr tools, and are portable enough to be attached to bugs, emails and many other forms of communication.
To generate your merge directive, simply execute the command below from your project directory.
bzr send lp:sahana-agasti/mayon -m "Includes new waffle-making functionality up-to trunk revisions r123" -o /some/file/location.bzr
In our case above, we start by pointing our merge directive back to its parent branch; this is so bzr can know what to diff against. Our send message should tell the branch maintainers what you introduced that was new and what base revision you merged from in the parent. The last file, /some/file/location.bzr is a file, anywhere on your filesystem, for the diff output. We'll need this file in the next step, so pay attention to where you put it!
Step 6: Create a Bug Report and Add your Directive
Now, you're ready to share your changes with the world! Open your favorite browser and go to our Launchpad Bugtracker. There, you should fill out a bug report describing your new patch, what it does, what series or versions it affects, and any other relevant changes.
At the bottom of the bug report you can then attach a patch file by clicking extra options. Use this opportunity to attach the diff file you just created in the last step. Once you've sufficiently documented your changes and attached your patch, submit your bug report and move to the next (and final) step.
Step 7: Be Patient, but Be Active!
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 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.