HowToUseBzr

From AWN Wiki

Jump to: navigation, search

Contents

[edit] How To Use Bazaar

Bazaar is a decentralized revision control system used by AWN's developers and many others, primarily on Launchpad. Revision control involves keeping track of changes in software source code, and often encouraging team-based collaboration.

To learn about Bazaar on the command-line: 

   $ bzr help

To learn about Bazaar commands: 

   $ bzr help commands

[edit] Using Bazaar with Launchpad

This will explain how to MFA Degree take changes you have made and commit them to the Launchpad code repository. First, make sure you have completed the steps outlined in HowToDevelopWithLaunchpad.

1. Run the following to associate your launchpad account with bzr: 

bzr launchpad-login [account username]

where [account username] is your Launchpad username.

2. Decide on the "workflow" that you are going to use: There are two main workflows:

  • the classic "checkout-checkin" centralized model (which we will call "SVN-style", for the sake of brevity)
  • the "branch-merge-push" decentralized model (which we will call "DVCS-style").

Most of the time, developers should use the SVN-style model, so that history is preserved in a linear fashion. For example, here is what the revision log typically looks like: 

------------------------------------------------------------
revno: 12
committer: Bob <bob@example.com>
branch nick: project
timestamp: Wed 2008-01-02 12:00:00 -0500
message:
  Fix the build system.
------------------------------------------------------------
revno: 11
committer: Alice <alice@example.com>
branch nick: project
timestamp: Tue 2008-01-01 12:00:00 -0600
message:
  Fix bug #123.

This is what the revision log looks like when Bob commits to his tree, tries to push to the remote branch, is informed that the branches have diverged, merges the two branches together, and then "successfully" pushes: 

------------------------------------------------------------
revno: 12
committer: Bob <bob@example.com>
branch nick: project
timestamp: Wed 2008-01-02 12:05:00 -0500
message:
  merge
    ------------------------------------------------------------
    revno: 10.1.1
    committer: Alice <alice@example.com>
    branch nick: project
    timestamp: Tue 2008-01-01 12:00:00 -0600
    message:
      Fix bug #123.
------------------------------------------------------------
revno: 11
committer: Bob <bob@example.com>
branch nick: project
timestamp: Wed 2008-01-02 12:00:00 -0500
message:
  Fix the build system.

This is a bad practice, because if Alice had commented in bug #123 that it was fixed in revision 11, it would no longer be true, causing people more frustration. Additionally, in the web interface, merged revisions such as 10.1.1 are not shown by default, so they are effectively "lost", unless you know where to look.

The instance where a developer should use the DVCS-style model is when they're working on a feature that cannot logically be done in a single commit. For example, if Bob were refactoring the trash applet to be desktop-agnostic, it would make sense to have one commit moving all of the GNOME-specific code into one file, then adding additional backends in a separate commit, and then finally creating an interface so that each backend has the same API that the trash applet can call as the "final" commit of this branch.


3. Download a fresh branch. Using the trunk of awn-extras as an example (to find the proper URL, visit the "code" tab of the project and select the desired branch; the information will be listed next to "Download URL").

(SVN-style) (DVCS-style) 
bzr checkout lp:awn-extras awn-extras

bzr branch lp:awn-extras awn-extras
4. Apply any patches and/or make any changes.
5.

Update your branch, so that it has the latest changes from the remote branch (you may have to cd into the awn-extras directory that is created from the checkout): 

bzr update

Update your branch, so that it has the latest changes from the remote branch.: 

bzr pull
Note: You may have some conflicts when you update your branch. Bazaar's user guide has a section on handling conflicts.

Commit to the branch. If you are pushing to a "trunk", or especially a stable branch, please make sure your changes have been tested by others. 

bzr commit

There are some special flags for this command that you should be aware of: --author and --fixes. If you're applying someone else's patch, you should use the --author=AUTHOR flag. For example: --author="Alice <alice@example.com>". If your commit fixes a Launchpad bug, use the --fixes=lp:BUG_NUMBER flag. For example: --fixes=lp:123. For completeness, here's an example of a bzr commit command that Bob ran, which commits Alice's patch to fix bug #123: 

bzr commit --author="Alice <alice@example.com>" --fixes=lp:123

6. You should be prompted for your log message. Make sure the first line is the name of the applet/project you are working on plus a short summary of the changes in the commit, followed by a detailed list of changes. For example (note that the Launchpad web interface will auto-link to bugs): 

BlingSwitcher: mousewheel fixes
 * applied patch from bug #159025 to fix going from first to last
   viewport via mousewheel
Note: It is a good practice to put the bug number in both the --fixes flag and in the log message, as bzr's command line interface does not yet show the bug fixes metadata with the log command.

7. Save the file (the name should be pre-filled; even though it looks like gibberish, it is the proper filename), and close. Your changes should be committed.

8. In the time between when you branched the repository and when you are ready to push your changes to the remote branch, there may have been some changes in the remote branch. In order for your changes to push cleanly, you need to merge the changes from upstream. Run the following: 
bzr merge

Make a note of the revision number of the remote branch from which you're merging. You'll need it later. If the command's output states that there are conflicts, don't panic. Bazaar's user guide has a section on handling conflicts.

Once there are no more conflicts, you need to commit this merge into your local branch. Follow steps 5 through 7 again. A good commit message for a merge looks like this: 

Merge from [branch name], revision [revision]

where [branch name] is the name of the remote branch, and [revision] is the revision number that you noted earlier.

9. Now it is finally time to push your changes onto Launchpad, which will take your local branch commit and make the changes live. This full command is available on the Launchpad code page of the desired branch. Again, assuming awn-extras trunk (and you have access to commit to this branch): 

bzr push lp:awn-extras

Finally: Assuming all went well, your changes are now in the current revision, which has incremented by one, and will be downloaded by anyone doing a checkout or branch!

[edit] Creating Good Commits

A "good commit" has the following properties:

  • It only involves one unit of "work". This means that it deals with just one feature or bug. Examples of "units" include:
    • Adding an AwnTitle to an applet
    • Temporarily removing an applet from the build system due to breakage, plus the maintainer cannot be contacted
    • Fixing a bug reported in Launchpad
  • It has a descriptive log entry. See step six above for a good format.

These properties make it easier for people to pinpoint when bugs started to occur and revert said bugs. Additionally, maintainers have an easier time when writing the NEWS entries for releases.

See also: On Version Control "best practices", written by one of the Awn/Awn Extras developers.

[edit] External Links

Retrieved from "http://wiki.awn-project.org/HowToUseBzr"
Personal tools