The Linux Foundation

 
Bazaar

From The Linux Foundation

(Difference between revisions)
(Commit Rights: Update to reflect the rollout of PQM.)
(Remove old Issues section.)
(48 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Bazaar-NG =
+
= Bazaar =
  
Bazaar-NG (or "bzr") is the primary candidate for replacing CVS as the FSG's preferred [[Version Control]] system.  (The other is [[Mercurial]].)
+
Bazaar (or "bzr") is the [[Version Control]] system in use by several workgroups at the Linux Foundation.   
 +
 
 +
Bazaar was previously known as Bazaar-NG (to distinguish it from the older Bazaar project (or "baz"); most of the pages on this wiki still call it Bazaar-NG.
  
 
== Getting Started ==
 
== Getting Started ==
  
Bazaar-NG is available in several distributions, although most of them currenly provide an older version.  Access to the FSG's repositories is recommended with bzr 0.8 or higher.
+
Bazaar is available in nearly all recent distributions.  Access to the LF's repositories requires bzr 2.0 or higher.
  
Users of Fedora Core 5, Debian "etch", or Ubuntu "Dapper" can use their distribution's version of bzr.  For Debian 3.1 ("sarge"), a [http://backports.org/package.php?search=bzr backport] is available.
+
=== Prebuilt Bazaar ===
  
For other distributions, the current version of bzr can be downloaded from [http://bazaar-vcs.org/Download the Bazaar-NG download page].  It requires Python 2.4 and the "ElementTree" and "cElementTree" modules at minimum.  To use the "sftp" method of talking to external repositories, the "paramiko" and "pycrypto" modules are required.
+
Prebuilt binaries are available for a number of platforms via the [http://wiki.bazaar.canonical.com/Download Bazaar download page].
  
== Documentation ==
+
=== Installing from Source ===
  
The [http://bazaar-vcs.org/ Bazaar-NG Web site] is availableIn particular, the following links are useful:
+
The current version of bzr can be downloaded from [http://wiki.bazaar.canonical.com/SourceDownloads the Bazaar download page].  It requires Python 2.4 and the [http://effbot.org/zone/element-index.htm ElementTree] and [http://effbot.org/zone/celementtree.htm cElementTree] modules at minimum; the latter two modules are a part of Python 2.5 or laterTo use the "sftp" method of talking to external repositories, the [http://www.lag.net/paramiko/ paramiko] and [http://www.amk.ca/python/code/crypto.html pycrypto] modules are required.
  
* [http://bazaar-vcs.org/Installation Installation]
+
Bazaar's source tree is set up so it can be used easily without installing if necessary. Just run the "bzr" executable at the root of the source tree.
* [http://bazaar-vcs.org/IntroductionToBzr Introduction to Bzr]
+
* [http://bazaar-vcs.org/QuickHackingWithBzr Quick Hacking with Bzr]
+
* The [http://bazaar-vcs.org/BzrFAQ FAQ]
+
  
== Current Trial ==
+
=== Installing Plugins ===
  
Migration trials are being run as of this writing. They are available at the following URL:
+
[http://wiki.bazaar.canonical.com/BzrPlugins Plugins] are add-on code modules which extend bzr, enhancing current features and adding new ones.
  
  http://bzr.freestandards.org/
+
Distributions which package bzr itself often package plugins as well; search for a "bzrtools" package to see. For unpackaged plugins, the bzr site has [http://doc.bazaar.canonical.com/plugins/en/ good installation instructions].
  
This will become the final site for the repositories, and the current layout is approximately what they will be for the real migration. The repository is browseable, and has roughly the same functionality as cvsweb.  Unofficial user branches are stored in "unofficial"; official branches from the workgroups are stored in a workgroup directory, with released and development versions in subdirectories.
+
One plugin that looks useful for projects (such as LSB) which have multiple repositories is the "update-mirrors" plugin. With this plugin, a single command "bzr update-mirrors" in a directory that holds branches of multiple repositories can do the effect of a "bzr pull" on each.
  
To check out a copy:
+
=== Initial Setup ===
  
bzr branch <nowiki>http://bzr.freestandards.org/unofficial/</nowiki>''(repo)'' ''(localdir)''
+
(modified from [[http://doc.bazaar.canonical.com/bzr.dev/en/tutorials/tutorial.html here]]):
  
or:
+
One function of a version control system is to keep track of who changed what. In a decentralized system, that requires an identifier for each author that is globally unique. Most people already have one of these: an email address. Bzr will auto-generate an email address by looking up your username and hostname, but this is only right if you always run bzr from the same machine and don't use a different email address as your identifier (such as @linux-foundation.org). We need a user's commits to have the same identifier over time!  Here are some options:
  
bzr branch <nowiki>http://bzr.freestandards.org/lsb/3.1/</nowiki>''(repo)'' ''(localdir)''
+
<ol>
 +
<li><p>Set an email address via bzr whoami. This is the simplest way.</p>
  
The webserve interface in the browser has links to the repository that work.
+
<p>To set a global identity, use:</p>
  
== Issues with Bazaar-NG ==
+
<pre>
 +
% bzr whoami "Your Name <email@example.com>"
 +
</pre>
 +
If you’d like to use a different address for a specific branch, enter the branch folder and use:
 +
<pre>
 +
% bzr whoami --branch "Your Name <email@example.com>"
 +
</pre>
 +
</li>
 +
<li>Set the email address in the ~/.bazaar/bazaar.conf by adding the following lines. Please note that [DEFAULT] is case sensitive:
 +
<pre>
 +
[DEFAULT]
 +
email = Your Name <email@isp.com>
 +
</pre>
 +
</li>
 +
<li>
 +
Override the previous setting on a branch by branch basis by creating a branch section in ~/.bazaar/branches.conf by adding the following lines:
 +
<pre>
 +
[/the/directory/to/the/branch]
 +
email = Your Name <email@isp.com>
 +
</pre>
 +
</li>
 +
<li>
 +
Override the two previous options by setting the global environment variable $BZREMAIL or $EMAIL ($BZREMAIL will take precedence) to your full email address.
 +
</li>
 +
</ol>
  
=== Speed ===
+
== Documentation ==
  
By far, the biggest problem with bzr is its speed, particularly at doing the initial checkout. The initial checkout of the "build_env" repositiory in the trial has been timed to take as long as 25 minutes, and others have reported even longer times.  Local operations, and updates after the initial checkout, are much faster.
+
The [http://doc.bazaar.canonical.com/ Bazaar documentation site] has lots of useful info, although not specific to our usage.
  
The bzr developers have blamed this on an initial focus on correctness and functionality, rather than speed. Optimizing bzr is the primary goal of the 0.9 series. The current goal is to release bzr 1.0 within the next few months, so it's hoped that current speed problems are temporary.
+
CVS wizards may (or may not) benefit from [http://wiki.bazaar.canonical.com/BzrForCVSUsers BzrForCVSUsers].
  
In the meantime, Jeff Bailey has suggested that we distribute tarballs of each tree to use as an initial seed.  Downloading and untarring the tree, and doing a subsequent "bzr pull", should be much faster.  Once the initial tree has been successfully retrieved, subsequent operations on the tree should be acceptably fast.
+
== Repositories ==
  
An automated tarball download feature has been implemented in the current trial.  In the changelog mode, there is a "download" link, which will create and send a tarball to the user consisting of the .bzr directory of the repository.  This can be made into a working copy by untarring the tarball, changing into the root of the resulting tree, and running "bzr revert".  After this, the directory is functionally identical to a tree created with "bzr branch".
+
All LF repositories are available at the following URL:
  
=== Project Reorganization ===
+
http://bzr.linux-foundation.org/
  
It's been [http://lists.freestandards.org/pipermail/lsb-core/2006-May/000779.html pointed out] that bzr does not allow the checking out of subdirectories alone; you must check out the entire branchThus, it may not make sense to lump as many of the sub-projects together as they are currently organized in CVS.
+
The repository is browseable, and has roughly the same functionality as cvswebUnofficial user branches are stored in "unofficial"; official branches from the workgroups are stored in a workgroup directory, with released and development versions in subdirectories.
  
=== Commit Rights ===
+
To check out a copy:
  
With CVS, since it is very difficult to maintain a local branch, pretty much anyone who did serious development on the LSB was granted commit rights. With bzr, since each branch is local, that's no longer needed. Thus, many fewer developers need commit rights. The problem then becomes: how do we get changes made by individual developers back into the main tree?
+
  bzr branch <nowiki>http://bzr.linux-foundation.org/unofficial/</nowiki>''(project)'' ''(localdir)''
  
One approach is to set up something like a Patch Review Committee, who have the responsibility of merging changes from other developers in.  The danger is that changes from outside the Committee might get ignored.
+
or:
  
The bzr developers use an add-on for bzr called a "patch queue manager". Under this approach, maintenance of the official main tree is automated to some degree, with patches submitted via email or some other means. This is the solution we are planning to use. Access to the patch queue manager happens through the project web interface, which now contains a "merge" link on all repositories.
+
bzr branch <nowiki>http://bzr.linux-foundation.org/lsb/3.1/</nowiki>''(project)'' ''(localdir)''
  
Right now, PQM is accessible to everyone.  This won't work for the final deployment, of course; the current idea is to password-protect the submission page, using the directory for user access.
+
The webserve interface in the browser has links to the repository that work.
 
+
=== User Branches ===
+
 
+
Without CVS as a method of distributing patches through the official tree, we will need some other means of making new development available.  Allowing users to publish their bzr branches on an FSG site is the best way for this to happen.  The question, of course, is how to best do this.
+
 
+
The current trial has a "unofficial" section for user branches.  Currently, someone with root access has to intervene to allow a user branch; this needs to be done differently.
+
  
In addition, we should have a page somewhere on the site that points to unofficial trees we find interesting, but perhaps not interesting enough to grant them space on our server.
+
== Commit Access ==
  
=== Tags ===
+
In general, you do not need commit access to contribute.  Instead, branch from our read-only repositories, and send changes using "bzr send".  Changes can be sent to the [http://lists.linuxfoundation.org/mailman/listinfo/lsb-discuss lsb-discuss mailing list].
  
As of 0.8.x, bzr does not have a native tagging facility.  [http://bazaar-vcs.org/BzrTagging This page] explains the proposals for adding tags to bzrIn the short term, Martin Pool has recommended to us that we use the [http://michael.ellerman.id.au/bzr/plugins/tags/ tags plugin], which gives us approximately what [[Mercurial]] tags give us.
+
People with a history of contributing to the LSB can request commit access. To do this, first set up an account on [http://www.linuxfoundation.org/ the main Linux Foundation site].  Then, make a request to us via the mailing list or IRC. Be sure to include your LF user ID.
  
=== Other Problems ===
+
Once commit access is granted, read-write branches can be checked out over HTTPS, using your username and the 'https+urllib:' URL type.  For example, to check out the devel version of misc-test as user "foo", you'd use the following URL:
  
If you notice other issues, please add them to the wiki, or discuss them on the Discussion page if you prefer.
+
<pre>
 +
https+urllib://foo@bzr.linuxfoundation.org/lsb/devel/misc-test
 +
</pre>

Revision as of 20:57, 13 December 2012

Contents

Bazaar

Bazaar (or "bzr") is the Version Control system in use by several workgroups at the Linux Foundation.

Bazaar was previously known as Bazaar-NG (to distinguish it from the older Bazaar project (or "baz"); most of the pages on this wiki still call it Bazaar-NG.

Getting Started

Bazaar is available in nearly all recent distributions. Access to the LF's repositories requires bzr 2.0 or higher.

Prebuilt Bazaar

Prebuilt binaries are available for a number of platforms via the Bazaar download page.

Installing from Source

The current version of bzr can be downloaded from the Bazaar download page. It requires Python 2.4 and the ElementTree and cElementTree modules at minimum; the latter two modules are a part of Python 2.5 or later. To use the "sftp" method of talking to external repositories, the paramiko and pycrypto modules are required.

Bazaar's source tree is set up so it can be used easily without installing if necessary. Just run the "bzr" executable at the root of the source tree.

Installing Plugins

Plugins are add-on code modules which extend bzr, enhancing current features and adding new ones.

Distributions which package bzr itself often package plugins as well; search for a "bzrtools" package to see. For unpackaged plugins, the bzr site has good installation instructions.

One plugin that looks useful for projects (such as LSB) which have multiple repositories is the "update-mirrors" plugin. With this plugin, a single command "bzr update-mirrors" in a directory that holds branches of multiple repositories can do the effect of a "bzr pull" on each.

Initial Setup

(modified from [here]):

One function of a version control system is to keep track of who changed what. In a decentralized system, that requires an identifier for each author that is globally unique. Most people already have one of these: an email address. Bzr will auto-generate an email address by looking up your username and hostname, but this is only right if you always run bzr from the same machine and don't use a different email address as your identifier (such as @linux-foundation.org). We need a user's commits to have the same identifier over time! Here are some options:

  1. Set an email address via bzr whoami. This is the simplest way.

    To set a global identity, use:

    % bzr whoami "Your Name <email@example.com>"
    

    If you’d like to use a different address for a specific branch, enter the branch folder and use:

    % bzr whoami --branch "Your Name <email@example.com>"
    
  2. Set the email address in the ~/.bazaar/bazaar.conf by adding the following lines. Please note that [DEFAULT] is case sensitive:
    [DEFAULT]
    email = Your Name <email@isp.com>
    
  3. Override the previous setting on a branch by branch basis by creating a branch section in ~/.bazaar/branches.conf by adding the following lines:
    [/the/directory/to/the/branch]
    email = Your Name <email@isp.com>
    
  4. Override the two previous options by setting the global environment variable $BZREMAIL or $EMAIL ($BZREMAIL will take precedence) to your full email address.

Documentation

The Bazaar documentation site has lots of useful info, although not specific to our usage.

CVS wizards may (or may not) benefit from BzrForCVSUsers.

Repositories

All LF repositories are available at the following URL:

http://bzr.linux-foundation.org/

The repository is browseable, and has roughly the same functionality as cvsweb. Unofficial user branches are stored in "unofficial"; official branches from the workgroups are stored in a workgroup directory, with released and development versions in subdirectories.

To check out a copy:

bzr branch http://bzr.linux-foundation.org/unofficial/(project) (localdir)

or:

bzr branch http://bzr.linux-foundation.org/lsb/3.1/(project) (localdir)

The webserve interface in the browser has links to the repository that work.

Commit Access

In general, you do not need commit access to contribute. Instead, branch from our read-only repositories, and send changes using "bzr send". Changes can be sent to the lsb-discuss mailing list.

People with a history of contributing to the LSB can request commit access. To do this, first set up an account on the main Linux Foundation site. Then, make a request to us via the mailing list or IRC. Be sure to include your LF user ID.

Once commit access is granted, read-write branches can be checked out over HTTPS, using your username and the 'https+urllib:' URL type. For example, to check out the devel version of misc-test as user "foo", you'd use the following URL:

https+urllib://foo@bzr.linuxfoundation.org/lsb/devel/misc-test

[Article] [Discussion] [View source] [History]