Rev 4893: (nmb) Add loggerhead and plugins sections in admin-guide in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Mon Dec 14 11:13:45 GMT 2009
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 4893 [merge]
revision-id: pqm at pqm.ubuntu.com-20091214111344-g3sb77go2xfy1nby
parent: pqm at pqm.ubuntu.com-20091214093120-s9xi50yxgx12vumr
parent: v.ladeuil+lp at free.fr-20091214103034-40d5ek4gdr8cfibx
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2009-12-14 11:13:44 +0000
message:
(nmb) Add loggerhead and plugins sections in admin-guide
modified:
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
----------
+Loggerhead_ is a code browsing interface for Bazaar branches (now used in
+Launchpad). To see an example of Loggerhead in action, browse to
+http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/files 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
+``http://www.example.com:8080`` or to proxy this location behind a separate web
+server, for example at ``http://www.example.com/loggerhead/``. We will discuss
+both of these configurations below.
+
+.. _Loggerhead: http://launchpad.net/loggerhead
+
+Requirements
+~~~~~~~~~~~~
+
+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 http://www.owlfish.com/software/simpleTAL/download.html
+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
+``www.example.com``, then running
+
+::
+
+ $ serve-branches --host=www.example.com --port=8080 /srv/bzr
+
+will list all of the available branches under that directory on
+``http://www.example.com:8080/``, so that the ProjectX trunk could be browsed
+at ``http://www.example.com:8080/projectx/trunk``. 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
+above.
+
+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 http://127.0.0.1:8080/
+ ProxyPassReverse http://127.0.0.1:8080/
+ </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
+``http://www.example.com/loggerhead/projectx/trunk``.
+
+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 http://launchpad.net/loggerhead.
+
+
Other web interfaces
--------------------
+
+There are a number of other web interfaces available for Bazaar branches (see
+the list at http://bazaar-vcs.org/WebInterfaces) and we will just mention a
+couple of them here for their advantages in particular situations.
+
+trac+bzr (http://launchpad.net/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 (http://thoughts.enseed.com/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 (http://redmine.org/)
+ 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
+http://doc.bazaar-vcs.org/en/plugin-guide. For purposes of installation,
+plugins are simply python packages. They can be installed alongside Bazaar in
+the ``bzrlib.plugins`` package using each plugin's ``setup.py``. 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
+branches.
+
+email
+~~~~~
+
+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
+http://doc.bazaar-vcs.org/plugins/en/email-plugin.html. As examples, consider
+the following two possible configurations. A minimal one (uses
+``/usr/bin/mail``)
+
+::
+
+ [DEFAULT]
+ post_commit_to = projectx-commits at example.com
+
+and a more complicated one (using all of the options)
+
+::
+
+ [DEFAULT]
+ post_commit_url = http://www.example.com/code/projectx/trunk
+ post_commit_to = projectx-commits at example.com
+ post_commit_sender = donotreply at example.com
+ post_commit_mailer = smtplib
+ smtp_server = mail.example.com:587
+ smtp_username = bob
+ # smtp_password = 'not specified, will prompt'
+
+
+hookless-email
+~~~~~~~~~~~~~~
+
+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 example.com`` 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``.)
+
+::
+
+ $ bzr_hookless_email.py --email=projectx-commits at example.com \
+ --recurse /srv/bzr
+
+email-notifier
+~~~~~~~~~~~~~~
+
+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]
+
+ server=smtp.example.com
+ # 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 example.com
+ 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 example.com
+ from=donotreply at example.com
+ subject=$relative_path: New branch created
+
+ [removed-branches]
+ to=projectx-commits at example.com
+ from=donotreply at example.com
+ subject=$relative_path: Branch removed
+
+If this file is stored as ``/srv/bzr/email-notifier.conf``, then the command
+
+::
+
+ $ bzr-email-notifier.py --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.
+
+branchfeed
+~~~~~~~~~~
+
+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 http://bazaar-vcs.org/FeedGenerators for more
+on those tools.
+
Mirroring
---------
+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.
+
+push_and_update
+~~~~~~~~~~~~~~~
+
+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.
+
+automirror
+~~~~~~~~~~
+
+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 ``sftp://www.example.com/var/www/projectx`` (for example if
+ProjectX were a web project that we wanted to access at
+``http://www.example.com/projectx``), then we could include
+
+::
+
+ [DEFAULT]
+ post_commit_mirror = sftp://www.example.com/var/www/branches/trunk
+
+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.
+
+testrunner
+~~~~~~~~~~
+
+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
+
+::
+
+ [DEFAULT]
+ pre_change_branch_tip_test_command = nosetests
+
+in ``.bzr/branch/branch.conf``.
+
+checkeol
+~~~~~~~~
+
+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.)
+
+text_checker
+~~~~~~~~~~~~
+
+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