Rev 4893: (nmb) Add loggerhead and plugins sections in admin-guide in file:///home/pqm/archives/thelove/bzr/%2Btrunk/ Patch Queue Manager pqm at
Mon Dec 14 11:13:45 GMT 2009

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

revno: 4893 [merge]
revision-id: pqm at
parent: pqm at
parent: v.ladeuil+lp at
committer: Patch Queue Manager <pqm at>
branch nick: +trunk
timestamp: Mon 2009-12-14 11:13:44 +0000
  (nmb) Add loggerhead and plugins sections in admin-guide
  doc/en/admin-guide/code-browsing.txt codebrowsing.txt-20091205144603-lgpl0e0z6lzk2rdw-3
  doc/en/admin-guide/hooks-plugins.txt hooksplugins.txt-20091205144603-lgpl0e0z6lzk2rdw-5
=== modified file 'doc/en/admin-guide/code-browsing.txt'
--- a/doc/en/admin-guide/code-browsing.txt	2009-12-07 18:12:21 +0000
+++ b/doc/en/admin-guide/code-browsing.txt	2009-12-11 00:00:04 +0000
@@ -1,7 +1,128 @@
 Web-based code browsing
+Browsing the history of a project online is an important part of version
+control, since it allows people to easily see what happens in a branch
+without having to have a local, up-to-date copy of that branch.  There are a
+number of possible choices for browsing Bazaar branches on the web, but we
+will cover one of them in particular detail and briefly mention the other
+choices where they differ.
+Loggerhead_ is a code browsing interface for Bazaar branches (now used in
+Launchpad).  To see an example of Loggerhead in action, browse to
+ which is the loggerhead
+view of Bazaar's trunk branch.  Loggerhead runs as a web application on the
+server which is accessed over HTTP via a RESTful interface.  It is possible to
+run this application on its own dedicated port as
+```` or to proxy this location behind a separate web
+server, for example at ````.  We will discuss
+both of these configurations below.
+.. _Loggerhead:
+Loggerhead depends on a number of other Python packages for the various Web
+technologies that it builds on.  Some of these must be installed to use
+loggerhead, although some of them are optional.  From the loggerhead `README`
+file, these are
+1) SimpleTAL for templating.
+   On Ubuntu, `sudo apt-get install python-simpletal`
+   or download from
+2) simplejson for producing JSON data.
+   On Ubuntu, `sudo apt-get install python-simplejson`
+   or use `easy_install simplejson`.
+3) Paste for the server. (You need version 1.2 or newer of Paste.)
+   On Ubuntu, `sudo apt-get install python-paste`
+   or use `easy_install Paste`
+4) Paste Deploy  (optional, needed when proxying through Apache)
+   On Ubuntu, `sudo apt-get install python-pastedeploy`
+   or use `easy_install PasteDeploy`
+5) flup (optional, needed to use FastCGI, SCGI or AJP)
+   On Ubuntu, `sudo apt-get install python-flup`
+   or use `easy_install flup`
+Although directions for installing these on Ubuntu Linux are given, most other
+Linux distributions should package these dependencies, making installation
+easy.  For Windows and Mac OS X, they should all be ``easy_install``-able or at
+worst installable from the Python sources.
+Built-in Web Server
+Loggerhead has a built-in web server and when started with the
+``serve-branches`` command, that web server is started on a default port
+listening on the localhost.  If port 8080 (the default) is accessible on
+````, then running
+  $ serve-branches --port=8080 /srv/bzr
+will list all of the available branches under that directory on
+````, so that the ProjectX trunk could be browsed
+at ````.  Note that loggerhead
+provides HTTP access to the underlying Bazaar branches (similar to that
+described in `Smart server over HTTP(S)
+<other-setups.html#smart-server-over-http-s>`_), so this command should be run
+as a user without write privileges in ``/srv/bzr``.  By default, loggerhead
+only listens on the localhost, not any external ports, unless specified as
+Behind a Proxy
+A more common and more safe way to run loggerhead is behind another web server
+which will proxy certain requests to the loggerhead server on the localhost.
+To do this, you need to have PasteDeploy installed (see `Requirements`_).
+Assuming that your server has Apache running, you need to add configuration
+such as this to set up the proxy
+    <Location "/loggerhead/">
+        ProxyPass
+        ProxyPassReverse
+    </Location>
+If your proxy runs at some path within the server, then the ``serve-branches``
+command must be started with the ``--prefix`` option.  For this example, we
+could start loggerhead with the command
+  $ serve-branches --prefix=/loggerhead /srv/bzr
+This would allow the trunk branch of ProjectX to be browsed at
+Loggerhead comes with a script allowing it to run as a service on init.d based
+Linux systems.  Contributions to do a similar thing on Windows servers would
+be welcomed at
 Other web interfaces
+There are a number of other web interfaces available for Bazaar branches (see
+the list at and we will just mention a
+couple of them here for their advantages in particular situations.
+trac+bzr (
+  Trac is a popular web app that integrates a browser for branches, an issue
+  tracker and a wiki.  trac+bzr is a trac extension that allows for the
+  trac to be used with Bazaar.
+webbzr (
+  This is a notable solution because it is written in pure PHP for web hosts
+  that don't provide a way to run arbitrary Python applications such as Trac
+  or Loggerhead.
+Redmine (
+  Like trac, Redmine is a full project management application using the Ruby
+  on Rails framework.  It includes support for Bazaar branches.

=== modified file 'doc/en/admin-guide/hooks-plugins.txt'
--- a/doc/en/admin-guide/hooks-plugins.txt	2009-12-07 18:12:21 +0000
+++ b/doc/en/admin-guide/hooks-plugins.txt	2009-12-11 15:04:15 +0000
@@ -1,14 +1,310 @@
 Extending Bazaar with Hooks and Plugins
+Bazaar offers a powerful extension mechanism for adding capabilities.  In
+addition to offering full library API access to all of its structures, which
+can be useful for outside programs that would like to interact with Bazaar
+branches, Bazaar can also load *plugins* that perform specific tasks.  These
+specific tasks are specified by *hooks* that run during certain steps of the
+version control process.  
+For full documentation on the available hooks, see ``bzr help hooks``.  Among
+those, some of the most significant hooks from an administration
+standpoint are `pre_commit`, `post_commit` and `post_change_branch_tip`.
+A `pre_commit` hook can inspect a commit before it happens and cancel it if
+some criteria are not met.  This can be useful for enforcing policies about
+the code, such as line-endings or whitespace conventions.  A
+`post_commit` hook can take actions based on the commit that just happened,
+such as providing various types of notifications.  Finally, a
+`post_change_branch_tip` hook is a more general form of a `post_commit`
+hook which is used whenever the tip of a branch changes (which can happen in
+more ways than just committing).  This too can be used for notification
+purposes, as well as for backups and mirroring.
+Information on the whole range of Bazaar plugins is available at
+  For purposes of installation,
+plugins are simply python packages.  They can be installed alongside Bazaar in
+the ``bzrlib.plugins`` package using each plugin's ````.  They can
+also be installed in the plugin path which is the user's ``~/.bazaar/plugins``
+directory or can be specified with the ``BZR_PLUGIN_PATH`` environment
+variable.  See ``bzr help configuration`` for more on specifying the location
+of plugins.
 Email Notification
+A common need is for every change made on a branch to send an email message to
+some address, most often a mailing list.  These plugins provide that capability
+in a number of different ways.  
+The `email` plugin sends email from each individual developer's computer.  This
+can be useful for situations that want to track what each individual developer
+is working on.  On the downside, it requires that every developer's branches be
+configured individually to use the same plugin.  
+The next two plugins `hookless-email` and `email-notifier` address this concern
+by running on a central server whenever changes happen on centrally stored
+To configure this plugin, simply install the plugin and configure the
+``post_commit_to``  option for each branch.  This configuration can be done
+in the ``locations.conf`` file or individually in each branch's
+``branch.conf`` file.  The sender's email address can be specified as
+``post_commit_sender`` if it is different than the email address reported by
+``bzr whoami``.  The ``post_commit_mailer`` option specifies how the
+mail should be sent.  If it isn't set, email is sent via ``/usr/bin/mail``.
+It can also be configured to communicate directly with an SMTP server.
+For more details on configuring this plugin, see
+  As examples, consider
+the following two possible configurations.  A minimal one (uses
+  post_commit_to = projectx-commits at
+and a more complicated one (using all of the options)
+  post_commit_url =
+  post_commit_to = projectx-commits at
+  post_commit_sender = donotreply at
+  post_commit_mailer = smtplib
+  smtp_server =
+  smtp_username = bob
+  # smtp_password = 'not specified, will prompt'
+This plugin is basically a server-side version of the `email` plugin.  It is
+a program that runs either from the command line or as a daemon that monitors
+the branches specified on the command line for any changes.  When a change
+occurs to any of the monitored branches, it will send an email to the
+specified address.  Using our simple example, the following command would send
+an email to ``projectx-commits at`` on any of the branches under
+``/srv/bzr`` since the last time the command was run.  (This command could be
+set up to run at regular intervals, for example from ``cron``.)
+  $ --email=projectx-commits at \
+  --recurse /srv/bzr
+This is a more elaborate version of the `hookless-email` plugin that can send
+templated HTML emails, render wiki-style markup in commit messages and update
+working copies on the server (similar to `push_and_update`_).  It can also
+send emails reporting the creation of new branches or the removal of branches
+under a specified directory (here ``/srv/bzr/projectx``).  As it is more
+complicated, its configuration is also more complicated and we won't repeat
+its documentation here, but a simple configuration that will send emails on
+commits and creation/deletion of branches is
+  [smtp]
+  # If user is not provided then no authentication will be performed.
+  user=bob
+  password=pAssW0rd
+  [commits]
+  # The address to send commit emails to. 
+  to=projctx-commits at
+  from=$revision.committer
+  # A Cheetah template used to construct the subject of the email message.
+  subject=$relative_path: $revision_number $summary
+  [new-branches]
+  to=projectx-commits at
+  from=donotreply at
+  subject=$relative_path: New branch created
+  [removed-branches]
+  to=projectx-commits at
+  from=donotreply at
+  subject=$relative_path: Branch removed
+If this file is stored as ``/srv/bzr/email-notifier.conf``, then the command
+  $ --config=/srv/bzr/email-notifier.conf /srv/bzr/projectx
+will watch all branches under the given directory for commits, branch
+creations and branch deletions.
 Feed Generation
+A related concept to sending out emails when branches change is the generation
+of news feeds from changes on each branch.  Interested parties can then choose
+to follow those news feeds in order to see what is happening on a branch.
+This plugin creates an ATOM feed for every branch on every branch change
+(commit, etc.).  It stores these files as ``.bzr/branch/branch.atom`` inside
+each branch.  Currently, it includes the 20 most recent changes in each feed.
+To use it, simply install the plugin and set your feed reader to follow the
+``branch.atom`` files.
+In addition, there are other tools that are not plugins for creating news
+feeds from Bazaar branches.  See for more
+on those tools.
+Sometimes it is useful to ensure that one branch exists as an exact copy of
+another.  This can be used to provide simple backup facilities or redundancy
+(see `Back-up and restore <backup.html>`_ for more details on backups).  One
+way to do this using Bazaar's workflows is to make the branch where changes
+happen into a bound branch of the mirror branch.  Then, when commits happen on
+the working branch, they will also happen on the mirror branch.  Note that
+commits to bound branches do *not* update the mirror branch's working copy, so
+if the mirror branch is more than just a backup of the complete history of the
+branch, for example if it is being served as a web page, then additional
+plugins are necessary.
+This plugin updates Bazaar's ``push`` command to also update the remote
+working copy.  It can only work over connections that imply filesystem or SSH
+access to the remote working copy (``bzr+ssh://``, ``sftp://`` and
+``file://``).  Also, it is only useful when the remote branch is updated with
+an explicit ``push`` command.
+This plugin is similar to `push_and_update` in that it updates the working
+copy of a remote branch.  The difference is that this plugin is designed to
+update the remote branch on every change to the working branch.  To configure
+this, set the ``post_commit_mirror = URL`` option on a branch.  This option
+can include multiple branch URLs separated by commas to create multiple
+mirrors.  For example, if we want to mirror our ``/srv/bzr/projectx/trunk``
+branch to the URL ``s`` (for example if
+ProjectX were a web project that we wanted to access at
+````), then we could include
+  post_commit_mirror = s
+in the file ``/srv/bzr/projectx/trunk/.bzr/branch/branch.conf``.
 Other Useful Plugins
+pqm (plugin)
+Facilitating interaction with `PQM
+<integration.html#patch-queue-manager-pqm>`_, this plugin provides support for 
+submitting merge requests to a remote Patch Queue Manager.  PQM provides 
+a way to automatically run the test suite before merging changes to the
+trunk branch.
+Sometimes referred to as the poor man's PQM, this plugin runs a single command
+on the updated revision (in a temporary directory) and if the command returns
+0, then the revision can be committed to that branch.  For example, if the
+testsuite is run with the command ``nosetests`` in the root of the branch
+(which returns 0 if the test suite passes and 1 if it doesn't pass), then one
+can set 
+  pre_change_branch_tip_test_command = nosetests
+in ``.bzr/branch/branch.conf``.
+This plugin is an example of a `pre_commit` hook that checks the revision
+being committed for meeting some policy.  In this case, it checks that all of
+the files have the specified line endings.  It uses a configuration file
+``.bzreol`` in the root of the working tree (similar to the ``.bzrignore``
+file).  This configuration file has sections for line feed endings (LF),
+carriage return/line-feed endings (CRLF) and carriage return endings (CR).
+For an unusual example that specifies different line endings for different
+files, that file might look like
+  [LF]
+  *.py
+  *.[ch]
+  [CRLF]
+  *.txt
+  *.ini
+  [CR]
+  foo.mac
+or if you simply want to enforce a single line ending convention on the branch
+you can use
+  [LF]
+  *
+This plugin needs to be installed on the server where the branch updates will
+happen, and the ``.bzreol`` file must be in each branch where line ending
+policies will be enforced.  (Adding it to the branch with ``bzr add .bzreol``
+is an easy way to ensure this, although it means that branches on the server
+must have working trees.)
+This plugin is a more advanced version of `checkeol` that can check such
+coding style guidelines such as trailing whitespace, long lines and files that
+don't end with a newline.  It is configured using Bazaar's built in rules
+specification in ``BZR_HOME/rules`` (see ``bzr help rules`` for more
+information.  For different types of undesired changes, you can specify
+different types of actions.  For example
+  [name NEWS README]
+  trailing_whitespace=fail
+  long_lines=warn
+  newline_at_eof=ignore
+  [name *.py]
+  tabs=fail
+  long_line_length=78
+  long_lines=fail
+  trailing_whitespace=fail
+will prevent changes from adding new trailing whitespace to the specified
+files and keep all python source files free of tabs and lines over 78
+characters.  To commit while violating these rules, one can pass the
+``--text-check-warn-only`` option to commit.

More information about the bazaar-commits mailing list