Merge lp:~nmb/bzr/admin-guide into lp:bzr

[Neil Martinsen-Burrell]

[Neil Martinsen-Burrell (nmb)]

This adds content to the System Administrator's Guide, while also structuring that content as separate files for each "chapter". There is great room for improvement in many of these topics, particularly the ones that are completely empty (integration.txt, security.txt), but I think it's worth merging this and then doing further changes to improve it. The only exception would be egregious errors which should be corrected before merging any version of it.

I understand it's a lot of text and hopefully we can get some kind of meaningful reviews in order to get it merged.

[Neil Martinsen-Burrell (nmb)]

Also this currently isn't accessible anywhere from doc/en/index.txt, but that is also an orthogonal change, although one that should be made soon after merging this. But, that really needs the attention of someone who knows what they want the doc website to look like. Ian?

[Vincent Ladeuil (vila)]

Impressive work !

But its size makes it quite hard to review :-/

Could you instead make several merge proposals starting with the
one that introduce the new layout and then one for each
significant topic (look at the prerequisite branch when making
these proposals) ?

Ideally each of one would then represent a ~100-300 lines diff
and be easier to review and provide timely and constructive
feedback. If you could end up with say 5 proposals instead of
this big one, I think we'll be in a better position to land
quickly most of them and let discussions happen where needed.

To keep the ball rolling, here are some remarks anyway:
- I agree the admin guide needs an entry at the root level,

- the html files doesn't seem to be generated by 'make docs',
  including that in the first mp would be good

- I don't think the migration chapter should stay here, I think
  it deserves its own guide and also its own entry at the root
  level.

review: Needs Fixing

[Neil Martinsen-Burrell (nmb)]

Will do. Resubmitting as six separate merge proposals with smaller diffs.

review: Needs Resubmitting

[Ian Clatworthy (ian-clatworthy)]

I'll make this patch as rejected as it's been superseded by the smaller patches.

=== added file 'doc/en/admin-guide/advanced.txt'
--- doc/en/admin-guide/advanced.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/advanced.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,160 @@
+Advanced Topics
+===============
+
+System Monitoring
+-----------------
+
+Capacity Planning Tips
+----------------------
+
+Clustering
+----------
+
+Multi-site Setups
+-----------------
+
+The "distributed" in distributed version control system should indicate that
+Bazaar is  well suited for multi-site development situations and indeed, that
+is the case.  The advantage comes from the ease and transparency of managing
+merges between branches with divergent history.  Note that there are many,
+many different ways to manage widely-flung development setups using Bazaar and
+its branching and merging capabilities.  These can be discovered and tested
+before being implemented as policy.  We will describe one such possible setup
+here.
+
+Consider ProjectX Corp's international expansion with a new branch office in
+Darwin, Australia, in addition to the company's headquarters in Paris, Texas,
+USA.  One of the difficulties of a far-flung multi-site development
+environment such as this is that the network connection between Australia and
+Texas is slow and unreliable.  So, each branch office would like the master
+branch to be local to them.  (In situations with good network connectivity, a
+local branch bound to the remote master may be all that is needed to support
+multi-site development.)
+
+Of course, with two master branches, there is always the question of which one
+is authoritative.  Given Bazaar's facility at managing multiple branches, we
+suggest that it is best not to privilege either the Texas or Australia
+branches, but to merge both of them into a separate master branch (which may
+reside at either site).  For definiteness, we will locate the master branch at
+the Texas site.  So, we will have three branches stored on two servers:
+trunk-master and trunk-texas at the Texas site and trunk-australia at the
+Darwin site.
+
+Setup
+~~~~~
+
+Using our previous setup at the Texas site, we will simply rename the old
+trunk branch as trunk-master and branch a copy as trunk-texas.
+
+::
+ 
+  $ cd /srv/bzr/projectx
+  $ mv trunk trunk-master              # can simply rename on the filesystem
+  $ bzr branch trunk-master trunk-texas   # very fast in a shared repository
+
+In Australia, we need to set up the ``/srv/bzr/projectx`` directory and get a
+copy of the current trunk as trunk-australia::
+
+  $ mkdir -p /srv/bzr
+  $ cd /srv/bzr
+  $ bzr init-repo --no-trees projectx
+  $ cd projectx
+  $ bzr branch bzr+ssh://server.example.com/srv/bzr/trunk-master
+  $ bzr branch trunk-master trunk-australia
+
+Merging to master
+~~~~~~~~~~~~~~~~~
+
+Then, each office works with their local copy of the trunk.  At some point,
+sooner or later depending on the pace of development in the two locations, the
+two local trunks need to be merged.  (In general, sooner beats later when
+merging, since there is no penalty for multiple merges.)  In this example,
+Alice at the Texas office will do the merging on her local machine using
+branches on the server::
+
+  # Get a copy of the Australia branch in Texas.  After the initial branch
+  # command, use pull to keep the branch up to date.  With a slow network,
+  # this is the only slow part
+  $ bzr branch bzr+ssh://autralia.example.com/srv/bzr/projectx/trunk-australia \
+    bzr+ssh://server.example.com/srv/bzr/projectx/trunk-australia
+  
+  # Check out the master branch locally for doing the merge
+  $ cd ~/projectx
+  $ bzr checkout bzr+ssh://server.example.com/srv/bzr/projectx/trunk-master
+  $ cd trunk-master
+  $ bzr merge bzr+ssh://server.example.com/srv/bzr/projectx/trunk-texas
+  # Run the test suite and resolve any conflicts
+  $ bzr commit -m "Merge Texas branch to master"
+  
+  # Now, merge from Australia using the local copy of that branch
+  $ bzr merge bzr+ssh://server.example.com/srv/bzr/projectx/trunk-australia
+  # Run the test suite and resolve any conflicts between the two offices
+  $ bzr commit -m "Merge Australia branch to master"
+
+Note that Bazaar does not commit even cleanly applied merges by default.  This
+is because although a merge may apply cleanly, the merged state still needs to
+be checked before it is committed.  (Just because there are no text conflicts
+does not mean that everything will work after a merge.)  If it is desired to
+automatically commit when possible, use ``bzr merge --pull``.
+
+Merging back to local trunks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now the trunk-master branch is the most up-to-date version of the software and
+both of the local trunks need to reincorporate the changes from the master.
+If no new commits have been made to trunk-texas, then that can happen using
+``bzr pull``::
+
+  $ cd ~/projectx
+  $ bzr checkout bzr+ssh://server.example.com/srv/bzr/projectx/trunk-texas
+  $ cd trunk-texas
+  $ bzr pull ../trunk-master  # Use trunk-master from the local disk
+                              # No need to commit
+
+If new changes have happened on trunk-texas since the integration with
+trunk-master, then the above pull will produce an error suggesting to use
+merge::
+
+  $ bzr merge ../trunk-master
+  # Run test suite, resolve conflicts
+  $ bzr commit -m "Merging Australian changes"
+
+In Australia, they will need to update their local copy of trunk-master::
+
+  $ cd /srv/bzr/projectx/trunk-master
+  $ bzr pull     # parent location is used by default
+
+Then, they need to pull or merge the changes from trunk-master into the local
+trunk.  This should be done by a developer with a checkout of trunk-australia
+so that they can run the test suite::
+
+  $ cd ~/projectx
+  $ bzr co bzr+ssh://australia.example.com/srv/bzr/projectx/trunk-australia
+  $ cd trunk-australia
+  $ bzr merge bzr+ssh://australia.example.com/srv/bzr/projectx/trunk-master
+  # Run test suite and integrate Texan changes with only recent local
+  # development
+  $ bzr commit -m "Integrate work from Texas"
+
+
+Other Considerations
+~~~~~~~~~~~~~~~~~~~~
+
+Multi-site deployments can be complicated, due to the many possible variations
+of development velocity, divisions of labor, network connectivity, resources
+for integration, etc.  The preceding description is meant to be one possible
+way to do fairly symmetric multi-site development.  (Neither Texas or
+Australia is privileged in this structure.)  In a situation where there is one
+main site and other smaller sites, one of the local trunk branches can be
+eliminated and trunk-master can be used directly for development at the main
+site.
+
+It is also up to the particular situation how frequently the local trunks are
+integrated into the master trunk.  Given resources specifically for
+integration, it is conceivable that a developer may be constantly responsible
+for integrating changes from the two teams.  Alternatively, the two sites
+could work on well-separated, well-defined features and merge to the master
+trunk only when their respective features are complete.  Given the difficulty
+of resolving conflicts in very large merges and the ease of merge handling in
+Bazaar, we suggest that merges be done more frequently, rather than less.
+more frequently
 
=== added file 'doc/en/admin-guide/backup.txt'
--- doc/en/admin-guide/backup.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/backup.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,144 @@
+Back-up and Restore
+===================
+
+Backing up Bazaar branches can be done in two different ways.  If an existing
+filesystem-based backup scheme already exists, then it can easily be used
+where the Bazaar branches reside.  Alternately, Bazaar itself can be used to
+mirror the desired branches to or from another location for backup purposes.
+
+Filesystem Backups
+------------------
+
+Bazaar transactions are atomic in the sense that the disk format is such that
+it is in a valid state at all times.  If a Bazaar file is copied while some
+process is in the midst of writing to that file, then that content is not
+referred to by the other on-disk structures until the data is completely
+written.  As such, it should be safe to copy Bazaar branches using filesystem
+tools at any time.  The only possible drawback to doing this is that the
+copied files may contain a small amount of additional content that isn't used
+elsewhere in the branch.  A later copy made after that change has fully
+completed would contain that whole change.  Bazaar's disk formats are not
+specifically tuned to be kind to tape backup methods that prefer to append to
+existing files, but they should be reasonably friendly in that regard.  (In
+many cases, they do only append to files that already exist.)
+
+
+Bazaar as its own backup
+------------------------
+
+The features that make Bazaar a good distributed version control system also
+make it a good choice for backing itself up.  In particular, complete and
+consistent copies of any branch can easily be obtained with the ``branch`` and
+``pull`` commands.  As a result, a backup process can simply run ``bzr pull``
+on a copy of the main branch to fully update that copy.  If this backup
+process runs periodically, then the backups will be as current as the last
+time that ``pull`` was run.  (This is in addition to the fact
+that revisions are immutable in Bazaar so that a prior revision of a branch is
+always recoverable from that branch when the revision id is known.)
+
+As an example, consider a separate backup server that stores backups in
+``/var/backup``.  On that server, we could initially run
+
+::
+
+  $ cd /var/backup
+  $ bzr branch bzr+ssh://server.example.com/srv/bzr/trunk
+  $ bzr branch bzr+ssh://server.example.com/srv/bzr/feature-gui
+
+to create the branches on the backup server.  Then, we could regularly (for
+example from ``cron``) do
+
+::
+
+  $ cd /var/backup/trunk
+  $ bzr pull  # the location to pull from is remembered
+  $ cd ../var/backup/feature-gui
+  $ bzr pull  # again, the parent location is remembered
+
+The action of pulling from the parent for all branches in some directory is
+common enough that there is a plugin to do it.  The `bzrtools`_ plugin
+contains a ``multi-pull`` command that does a ``pull`` in all branches under a
+specified directory.
+
+.. _bzrtools: http://launchpad.net/bzrtools
+
+With this plugin installed, the above periodically run commands would be
+
+::
+
+  $ cd /var/backup
+  $ bzr multi-pull
+
+Note that ``multi-pull`` does a pull in *every* branch in the specified
+directory (the current directory by default) and care should be taken that
+this is the desired effect.  A simple script could also substitute for the
+multi-pull command while also offering greater flexibility.
+
+Bound Branch Backups
+~~~~~~~~~~~~~~~~~~~~
+
+When ``bzr pull`` is run regularly to keep a backup copy up to date, then it
+is possible that there are new revisions in the original branch that have not
+yet been pulled into the backup branch.  To alleviate this problem, we can set
+the branches up so that new revisions are *pushed* to the backup rather than
+periodically pulling.  One way to do this is using Bazaar's concept of bound
+branches, where a commit in one branch happens only when the same commit
+succeeds in the branch to which it is `bound`.  As a push-type technology, it
+is set up on the server itself rather than on the backup machine.  For each
+branch that should be backed up, you just need to use the ``bind`` command to
+set the URL for the backup branch.  In our example, we first need to create
+the branches on the backup server (we'll use ``bzr push``, but we could as
+easily have used ``bzr branch`` from the backup server)
+
+::
+  $ cd /srv/bzr/projectx/trunk
+  $ bzr push bzr+ssh://backup.example.com/var/backup//trunk
+  $ cd ../feature-gui
+  $ bzr push bzr+ssh://backup.example.com/var/backup/feature-gui
+
+and then we need to bind the main branches to their backups
+
+::
+
+  $ cd ../trunk
+  $ bzr bind bzr+ssh://backup.example.com/var/backup/trunk
+  $ cd ../feature-gui
+  $ bzr bind bzr+ssh://backup.example.com/var/backup/feature-gui
+
+A branch can only be bound to a single location, so if multiple backups are
+desired, then the branches must be chained.  For example on the backup server,
+we could bind the backup branches to a separate, remote backup
+
+::
+
+  $ cd /var/backup/trunk
+  $ bzr push bzr+ssh://offsite.example.org/projectx-corp/backup/trunk
+  $ bzr bind bzr+ssh://offsite.example.org/projectx-corp/backup/trunk
+  $ cd ../feature-gui
+  $ bzr push bzr+ssh://offsite.example.org/projectx-corp/backup/feature-gui
+  $ bzr bind bzr+ssh://offsite.example.org/projectx-corp/backup/feature-gui
+
+Using the `automirror`_ plugin mentioned under `Hooks and Plugins <hooks-plugins.html>`_, one can
+also make a push-type backup system that more naturally handles mutliple
+backups.  Simply set the ``post_commit_mirror`` option to multiple URLs
+separated by commas.  Replicating the above example would mean doing
+
+::
+
+  $ cd /srv/bzr/trunk
+  $ echo "post_commit_mirror=bzr+ssh://backup.example.com/var/backup/trunk,\
+  bzr+ssh://offsite.example.org/projectx-corp/backup/trunk" >> .bzr/branch/branch.conf
+  $ cd ../feature-gui
+  $ echo "post_commit_mirror=bzr+ssh://backup.example.com/var/backup/feature-gui,\
+  bzr+ssh://offsite.example.org/projectx-corp/backup/feature-gui" >> .bzr/branch/branch.conf
+
+.. _automirror: http://launchpad.net/bzr-automirror
+
+As for any push-type backup strategy that maintains consistency, the downside
+of these methods is that all of the backup commits must succeed before the
+initial commit can succeed.  If there is a long chain of bound branches, many
+mirror branches, or if the bound branch has a slow network connection, then
+the delay in the original commit may be unacceptably long.  In this case,
+pull-type backups, or a mixed system may be preferable.
+
+
 
=== added file 'doc/en/admin-guide/code-browsing.txt'
--- doc/en/admin-guide/code-browsing.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/code-browsing.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,126 @@
+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 (originally
+developed for 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.
+
+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, the 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.
 
=== added file 'doc/en/admin-guide/hooks-plugins.txt'
--- doc/en/admin-guide/hooks-plugins.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/hooks-plugins.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,309 @@
+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` are designed to run 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 = [e-mail]
+
+and a more complicated one (using all of the options)
+
+::
+
+  [DEFAULT]
+  post_commit_url = http://www.example.com/code/projectx/trunk
+  post_commit_to = [e-mail]
+  post_commit_sender = [e-mail]
+  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 ``[e-mail]`` 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=[e-mail] \
+  --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=[e-mail]
+  from=$revision.committer
+
+  # A Cheetah template used to construct the subject of the email message.
+  subject=$relative_path: $revision_number $summary
+
+  [new-branches]
+  to=[e-mail]
+  from=[e-mail]
+  subject=$relative_path: New branch created
+
+  [removed-branches]
+  to=[e-mail]
+  from=[e-mail]
+  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.  It is possible
+to make a chain of bound branches to create multiple mirrors.  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.
+
+.. TODO: check that the list of URLs is correct
+
+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)
+~~~~~~~~~~~~
+
+Discussed further under `PQM <integration.html#patch-queue-manager-pqm>`_, this
+plugin submits each commit on a branch to the Patch Queue Manager, which can
+run the test suite before committing that revision to another 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.
+
 
=== modified file 'doc/en/admin-guide/index.txt'
--- doc/en/admin-guide/index.txt	2008-03-05 16:38:20 +0000
+++ doc/en/admin-guide/index.txt	2009-12-07 03:05:25 +0000
@@ -1,114 +1,25 @@
-==========================
-Bazaar Administrator Guide
-==========================
-
-Note: this is a work in progress!
-
-.. contents:: Table of contents
-   :depth: 2
-
-Introduction
-============
-
-Introduction to administering a Bazaar server installation.
-
-Scope of this guide
--------------------
-
-What you need to run a Bazaar server
-------------------------------------
-
-Platform requirements etc
-
-
-Simple setup
-============
-
-Smart server
-------------
-
-Recommended tools
------------------
-
-
-Migration
-=========
-
-Migrating from another VCS.
-
-Legacy VCS to bzr sync.
-
-
-Hooks
-=====
-
-
-Web-based code browsing
-=======================
-
-Loggerhead etc.
-
-
-Integration with other tools
-============================
-
-PQM
----
-
-Bug trackers
-------------
-
-Continuous integration tools
-----------------------------
-
-e.g. Cruise Control
-
-Bundle Buggy
-------------
-
-
-Security
-========
-
-Authentication
---------------
-
-ACLs
-----
-
-
-Back-up and restore
-===================
-
-
-Upgrades
-========
-
-Software upgrades
------------------
-
-Disk format upgrades
---------------------
-
-Plugin upgrades
----------------
-
-
-System monitoring
-=================
-
-
-Capacity planning tips
-======================
-
-Disk management etc.
-
-
-Advanced topics
-===============
-
-Clustering
-----------
-
-Multi-site setups
------------------
+###################################
+Bazaar System Administrator's Guide
+###################################
+
+.. Please mark sections in included files as following:
+..   level 1 ========
+..   level 2 --------
+..   level 3 ~~~~~~~~
+..   level 4 ^^^^^^^^ (it is better not to use nesting deeper than 3 levels)
+
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   simple-setups
+   other-setups
+   migration
+   hooks-plugins
+   code-browsing
+   integration
+   security
+   backup
+   upgrade
+   advanced
 
=== added file 'doc/en/admin-guide/integration.txt'
--- doc/en/admin-guide/integration.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/integration.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,14 @@
+Integration with Other Tools
+============================
+
+Patch Queue Manager (PQM)
+-------------------------
+
+Bug Trackers
+------------
+
+Continuous Integration Tools
+----------------------------
+
+Bundle Buggy
+------------
 
=== added file 'doc/en/admin-guide/introduction.txt'
--- doc/en/admin-guide/introduction.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/introduction.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,57 @@
+Introduction
+============
+
+Welcome to the Bazaar Version Control System's guide for system
+administrators.  Bazaar is a flexible system that provides many possible
+options for serving projects, in ways that will hopefully meet your needs.  If
+you have requirements that are not met by the current state of the Bazaar
+ecosystem, please let us know at [e-mail] on on Launchpad at
+https://launchpad.net/bzr.
+
+Scope of this guide
+-------------------
+
+In this guide, we will discuss various techniques for making Bazaar projects
+available, migrating from other Version Control Systems, browsing code over
+the Web and combining Bazaar with other tools.  In many of these categories,
+multiple options exist and we will try to explains the costs and benefits of
+the various options.
+
+The intended audience for this guide is the individuals who administer the
+computers that will do the serving.  Much of the configuration that we will
+discuss requires administrator privileges and we will not necessarily indicate
+every point that those privileges are needed.  That said, reading this guide
+can also be very helpful for those who are interested in communicating to the
+system administrators about the requirements for making full use of Bazaar.
+
+What you need to run a Bazaar server
+------------------------------------
+
+Where possible, we will discuss both Unix (including Linux) and Windows server
+environments.  For the purposes of this document, we will consider Mac OS X as
+a type of Unix.
+
+In general, Bazaar requires only Python_ 2.4 or greater and the cElementTree_
+package (included in Python 2.5 and later) to run.  If you would *optionally*
+like to be able to access branches using SFTP, you need `paramiko and
+pycrypto`_.
+
+.. _Python: http://www.python.org/
+.. _cElementTree: http://effbot.org/zone/element-index.htm
+.. _paramiko and pycrypto: http://www.lag.net/paramiko/
+
+For maximum performance, Bazaar can make use of compiled versions of some
+critical components of the code.  Pure Python alternatives exist for all of
+these components, but they may be considerably slower.  To compile these
+extensions, you need a C compiler and the relevant header files from the
+Python package.  On Linux, these may be in a separate package.  Other
+operating systems should have the required headers installed by default.
+
+If you are installing a development version of Bazaar, rather than a released
+version, you will need Pyrex_ to create the C extensions.  The release
+tarballs already have the Pyrex-created C files.
+
+.. _Pyrex: http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/
+
+
+
 
=== added file 'doc/en/admin-guide/migration.txt'
--- doc/en/admin-guide/migration.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/migration.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,68 @@
+Migration
+=========
+
+Fast Import
+-----------
+
+In many projects wishing to use Bazaar, there is pre-existing history for the
+codebase that should be taken into consideration.  Bazaar leverages an
+interchange format originally developed for Git called `fast-import` to
+provide migration strategies for many other version control systems.  To
+work with fast-import files, Bazaar needs the `fastimport`_ plugin.  This can
+be installed as with any Bazaar plugin.
+
+.. _fastimport: http://launchpad.net/bzr-fastimport
+
+The way that fast-import can be used for migration is to export the existing
+history into a fast-import file, then use the ``bzr fast-import`` command.
+The `fastimport` plugin includes exporters for Subversion, CVS, Git, Mercurial
+and darcs, accessible as the ``fast-export-from-XXX`` commands.  Note that
+``fast-import`` should not be used in a branch with existing history.
+
+Assuming that ProjectX was first developed in Mercurial before switching to
+Bazaar, and that the Mercurial repository is in ``/srv/hg/projectx``, the
+following commands will import that history into a newly created ``trunk``
+branch.  (Recall that in `Further Configuration
+<simple-setups.html#further-configuration>`_ we created the
+``/srv/bzr/projectx`` directory as a shared repository.)
+
+::
+
+  $ cd /srv/bzr/projectx
+  $ bzr fast-export-from-hg ../../hg/projectx projectx.fi
+  $ bzr init trunk
+  $ bzr fast-import projectx.fi trunk
+
+Subversion Conversion
+---------------------
+
+As the most common centralized version control system, migration from
+Subversion is particularly important for any *new* version control system.
+Bazaar's `svn`_ plugin provides tools for interaction with Subversion
+projects.  In fact, Bazaar can be used transparently with projects stored in
+Subversion, but that is beyond the scope of this document.  (See
+http://doc.bazaar-vcs.org/en/migration/foreign/bzr-on-svn-projects.html for
+more on that subject.)  What is relevant here is the ``svn-import`` command
+provided by that plugin.  This can import an entire subversion repository
+including tags and branches, particularly if they are stored in Subversion's
+recommended directory structure: ``/tags/``, ``/branches/`` and ``/trunk/``.
+
+This command has flexible ways to specify what paths within the Subversion
+repository contain branches and which contain tags.  For example, the
+recommended layout for Subversion projects (called ``trunk`` by the svn
+plugin) could be specified in ``~/.bazaar/subversion.conf`` as
+
+::
+
+  [203ae883-c723-44c9-aabd-cb56e4f81c9a]
+  branches = branches/*
+  tags = tags/*
+
+This allows substantially complicated Subversion repositories to be converted
+into a set of separate Bazaar branches.  After installing the svn plugin, see
+``bzr help svn-import`` and ``bzr help svn-layout``.
+
+.. _svn: http://launchpad.net/bzr-svn
+
+.. TODO: Legacy VCS to bzr sync.  Tailor?  Incremental conversions?
+
 
=== added file 'doc/en/admin-guide/other-setups.txt'
--- doc/en/admin-guide/other-setups.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/other-setups.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,60 @@
+Other Setups
+============
+
+Dumb servers
+------------
+
+Bazaar can also serve branches over protocols that know nothing about Bazaar's
+specific needs.  These are called "dumb servers" to distinguish them from
+Bazaar's native protocol.  Currently HTTP, FTP, SFTP and HTTP+WebDAV can be
+used to read branches remotely.  FTP, SFTP and HTTP+WebDAV can be used for
+writing as well.  To use any of these protocols, it is just necessary to
+provide access to the server's filesystem under ``/srv/bzr``.
+
+For example, for Apache to provide read-only access to the branches
+in ``/srv/bzr`` the configuration may look like this::
+
+  Alias /code /srv/bzr
+  <Directory /srv/bzr>
+      Options Indexes
+      # ...
+  </Directory>
+
+and users could use the URL ``http://server.example.com/code/projectx/trunk``
+to refer to the trunk branch.
+
+Note that SFTP access is often available whenever there is SSH access, but it
+may be a good choice when Bazaar cannot be installed on the server to allow
+``bzr+ssh://`` access.  Dumb servers are slower by their very nature than the
+native protocol, but they can be a good choice in situations where the
+software and protocols that can be used on the server or the network is
+limited.
+
+Smart server over HTTP(S)
+-------------------------
+
+Bazaar can use its native protocol with HTTP requests.  Since HTTP is a
+network protocol that is available on many networks, this can be a good option
+where SSH access is not possible.  Another benefit of this setup is that all
+of the authentication and access control methods available to the HTTP server
+(basic, LDAP, ActiveDirectory, etc.) are then available to control access to
+Bazaar branches.  More information about setting up this type of access using
+Apache and FastCGI or mod_python or WSGI is in the 
+`User's Guide <../user-guide/http_smart_server.html>`_.
+
+Direct Smart Server Access
+--------------------------
+
+The built-in server that is used by ``bzr+ssh://`` access can also be used as
+a persistent server on a dedicated port.  Bazaar's official port is 4155,
+although the port used can be configured.  Further information on running the
+Bazaar smart server from inetd, or directly from the shell is in the `User's
+Guide <../user-guide/server.html#inetd>`_.  The dedicated Bazaar server does not
+currently perform any authentication, so this server by default provides
+read-only access.  It can be run with the ``--allow-writes`` option, but if
+the user that the server is running as has write access to the branch
+directories on the filesystem, then this will allow anyone with access to port
+4155 on the server to make changes to the branches stored there. 
+
+
+
 
=== added file 'doc/en/admin-guide/security.txt'
--- doc/en/admin-guide/security.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/security.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,9 @@
+Security
+========
+
+Authentication
+--------------
+
+Access Control
+--------------
+
 
=== added file 'doc/en/admin-guide/simple-setups.txt'
--- doc/en/admin-guide/simple-setups.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/simple-setups.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,92 @@
+Simple Setups
+=============
+
+Consider the following simple scenario where we will be serving Bazaar
+branches that live on a single server.  Those branches are in the
+subdirectories of ``/srv/bzr`` (or ``C:\\bzr``) and they will all be related to a
+single project called "ProjectX".  ProjectX will have a trunk branch and at
+least one feature branch.  As we get further, we will consider other
+scenarios, but this will be a sufficiently motivating example.
+
+Smart server
+------------
+
+The simplest possible setup for providing outside access to the branches on
+the server uses Bazaar's built-in smart server tunneled over SSH_ so
+that people who can access your server using SSH can have read and write
+access to branches on the server.  This setup uses the authentication
+mechanisms of SSH including private keys, and the access control mechanisms of
+the server's operating system.  In particular, using groups on the server, it
+is possible to provide different access privileges to different groups of
+developers.
+
+.. _SSH: http://www.openssh.org/
+
+Setup
+~~~~~
+
+There is no setup required for this on the server, apart from having Bazaar
+installed and SSH access available to your developers.  Using SSH
+configuration options it is possible to restrict developers from using
+anything *but* Bazaar on the server via SSH, and to limit what part of the
+file system they can access.
+
+Client
+~~~~~~
+
+Clients can access the branches using URLs with the ``bzr+ssh://`` prefix.  For
+example, to get a local copy of the ProjectX trunk, a developer could do::
+
+  $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk projectx
+
+If the developers have write access to the ``/srv/bzr/projectx`` directory, then
+they can create new branches themselves using::
+  
+  $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk \
+  bzr+ssh://server.example.com/srv/bzr/projectx/feature-gui
+
+Of course, if this isn't desired, then developers should not have write access
+to the ``/srv/bzr/projectx`` directory.
+
+Further Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+For a project with multiple branches that are all related, it is best to use a
+shared repository to hold all of the branches.  To set this up, do::
+
+  $ cd /srv/bzr
+  $ bzr init-repo --no-trees projectx
+
+The ``--no-trees`` option saves space by not creating a copy of the working
+files on the server's filesystem.  Then, any branch created under
+``/srv/bzr/projectx`` (see `Migration <migration.html>`_ for some ways to do
+this) will share storage space, which is particularly helpful for branches that
+have many revisions in common, such as a project trunk and its feature
+branches.
+
+If Bazaar is not installed on the user's path or not specified in the SSH
+configuration, then a path can be specified from the client with the
+``BZR_REMOTE_PATH`` environment variable.  For example, if the Bazaar executable
+is installed in ``/usr/local/bzr-2.0/bin/bzr``, then a developer could use::
+
+  $ BZR_REMOTE_PATH=/usr/local/bzr-2.0/bin/bzr bzr info \
+  bzr+ssh://server.example.com/srv/bzr/proectx/trunk
+
+to get information about the trunk branch.  The remote path can also be
+specified in Bazaar's configuration files for a particular location.  See
+``bzr help configuration`` for more details.
+
+If developers have home directories on the server, they can use ``/~/`` in
+URLs to refer to their home directory.  They can also use ``/~username/`` to
+refer to the home directory of user ``username``.  For example, if there are two
+developers ``alice`` and ``bob``, then Bob could use::
+
+  $ bzr log bzr+ssh://server.example.com/~/fix-1023
+
+to refer to one of his bug fix branches and::
+
+  $ bzr log bzr+ssh://server.example.com/~alice/fix-2047
+  
+to refer to one of Alice's branches.
+
+
 
=== added file 'doc/en/admin-guide/upgrade.txt'
--- doc/en/admin-guide/upgrade.txt	1970-01-01 00:00:00 +0000
+++ doc/en/admin-guide/upgrade.txt	2009-12-07 03:05:25 +0000
@@ -0,0 +1,76 @@
+Upgrades
+========
+
+Bazaar has a strong commitment to inter-version compatibility both on disk and
+over the network.  Newer clients should be able to interact with older
+versions on the server (although perhaps not at optimal speed) and older
+clients should also be able to communicate with newer versions of Bazaar on
+the server.  Divergences from this rule are considered bugs and are fixed in
+later versions.
+
+That said, Bazaar is constantly improving and the most recent versions are the
+most featureful and have better performance.  In particular, the Bazaar
+versions after 2.0 have significant advantages over earlier versions,
+including a more compact disk format, faster network operations and overall
+performance improvements.  With the 2.0 release, Bazaar has moved to a
+stable/development release model where the 2.x series is maintained with
+bugfixes releases for six months, while simultaneously the 2.(x+1) series is
+being developed with monthly beta releases that are suitable for everyday use.
+Bazaar development has a stable trunk with an extensive test suite, so there
+is no reason to fear using the development series for everyday use, it simply
+changes more often than the stable series.
+
+
+Software upgrades
+-----------------
+
+Upgrading the Bazaar software is as simple re-installing the Python package
+using either the latest binary package for Windows or Mac OS X, the binary
+package provided by your Linux distribution, or installing from the source
+release.  See http://bazaar-vcs.org/Downloads for the latest releases for all
+supported platforms.
+
+Bazaar's later versions support all of the earlier disk formats (back to the
+very first one), so there is no need to upgrade the branches on the disk when
+upgrading the software.  To make use of particular new features that might
+need updated versions on both the server and developer's machines, it does not
+matter if the clients or the servers are upgraded first.
+
+
+Disk format upgrades
+--------------------
+
+In its evolution, Bazaar has used a sequence of disk formats for improved
+storage efficiency and speed.  With the new disk format released in version
+2.0, there is a commitment to keep that disk format until version 3.0 is
+released, which has not even been planned yet.  (Bazaar 2.0 was released
+almost two years after Bazaar 1.0.)  As a result, disk format upgrades should
+be extremely infrequent.
+
+If there are existing branches in an older format that you would like to
+upgrade to the latest format, you can see the `2.0 Upgrade Guide
+<../upgrade-guide/index.html>`_ for more information.  From the system
+administration perspective, it is important to coordinate the timing of
+various upgrades in the process.  First, the central branches on the server
+should be upgraded.  Next, any local mirrors that developers have should be
+upgraded.  Finally, developers' local branches should be upgraded.  These
+upgrades will require an appropriate version of the software whenever they are
+performed.  (It is possible to upgrade branches remotely over the network, but
+it may be much slower.)
+
+
+Plugin upgrades
+---------------
+
+When Bazaar does update its version, plugins that use the Bazaar API may need
+to be upgraded to reflect changes in that API.  Some plugins have strict
+version dependencies on the version of the Bazaar API that they will accept.
+If this is the case, then you should ensure that the plugins you depend on
+have been updated *before* you upgrade your Bazaar version to avoid a
+situation where your plugins won't work with the installed version of Bazaar.
+If this does happen, then the solution is simply to reinstall the previous
+version of Bazaar that *did* work with the plugins.  For installations that
+depend on a large number of plugins, this sort of version upgrade should be
+tested in a safe sandbox to ensure that the entire collection of Bazaar and
+its plugins can all work together.
+
 
=== modified file 'doc/en/conf.py'
--- doc/en/conf.py	2009-09-09 13:34:08 +0000
+++ doc/en/conf.py	2009-12-07 03:05:25 +0000
@@ -73,8 +73,6 @@
 
 # List of documents that shouldn't be included in the build.
 unused_docs = [
-    # Placeholder for later
-    'admin-guide/index',
     # Subtopics that get included
     'upgrade-guide/overview',
     'upgrade-guide/data_migration',
 
=== modified file 'doc/en/index.txt'
--- doc/en/index.txt	2009-09-09 11:43:10 +0000
+++ doc/en/index.txt	2009-12-07 03:05:25 +0000
@@ -16,3 +16,4 @@
    release-notes/index
    upgrade-guide/index
    user-reference/index
+   admin-guide/index