Rev 2620: (James Westby) documentation updates (plugins, configuration, etc) in http://bzr.arbash-meinel.com/branches/bzr/jam-integration
John Arbash Meinel
john at arbash-meinel.com
Mon Jul 16 20:56:00 BST 2007
At http://bzr.arbash-meinel.com/branches/bzr/jam-integration
------------------------------------------------------------
revno: 2620
revision-id: john at arbash-meinel.com-20070716195536-7swyum1epmk0313d
parent: pqm at pqm.ubuntu.com-20070716084122-jfjzwtbimsjv0iqv
parent: jw+debian at jameswestby.net-20070713224426-n74sjf5wwvpm1n0n
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: jam-integration
timestamp: Mon 2007-07-16 14:55:36 -0500
message:
(James Westby) documentation updates (plugins, configuration, etc)
added:
doc/bug_trackers.txt bug_trackers.txt-20070713223459-khxdlcudraii95uv-1
modified:
doc/README.1st README.1st-20060314161707-b943d5d4cce669b6
doc/configuration.txt configuration.txt-20060314161707-868350809502af01
doc/http_smart_server.txt fastcgi.txt-20061005091552-rz8pva0olkxv0sd8-3
doc/plugins.txt plugins.txt-20060314145616-525099a747f3ffdd
------------------------------------------------------------
revno: 2601.1.3
revision-id: jw+debian at jameswestby.net-20070713224426-n74sjf5wwvpm1n0n
parent: jw+debian at jameswestby.net-20070713223936-nyumc0ogoses82cf
committer: James Westby <jw+debian at jameswestby.net>
branch nick: bzr.dev.docs
timestamp: Fri 2007-07-13 23:44:26 +0100
message:
Put plugin installation instructions before how to write them.
Also add a note that plugin installation directories must have names
that are valid python identifiers.
modified:
doc/plugins.txt plugins.txt-20060314145616-525099a747f3ffdd
------------------------------------------------------------
revno: 2601.1.2
revision-id: jw+debian at jameswestby.net-20070713223936-nyumc0ogoses82cf
parent: jw+debian at jameswestby.net-20070713223507-lpvkrwy79opb29oo
committer: James Westby <jw+debian at jameswestby.net>
branch nick: bzr.dev.docs
timestamp: Fri 2007-07-13 23:39:36 +0100
message:
Add a reference to the main smart server documentation.
modified:
doc/http_smart_server.txt fastcgi.txt-20061005091552-rz8pva0olkxv0sd8-3
------------------------------------------------------------
revno: 2601.1.1
revision-id: jw+debian at jameswestby.net-20070713223507-lpvkrwy79opb29oo
parent: pqm at pqm.ubuntu.com-20070711162842-8fx9cc0c3ogyxudl
committer: James Westby <jw+debian at jameswestby.net>
branch nick: bzr.dev.docs
timestamp: Fri 2007-07-13 23:35:07 +0100
message:
Split out bug tracker configuration in to its own file.
Make a few small changes in configuration.txt as well.
Maybe configuration.txt should have a link to the bug_trackers.txt
file.
added:
doc/bug_trackers.txt bug_trackers.txt-20070713223459-khxdlcudraii95uv-1
modified:
doc/README.1st README.1st-20060314161707-b943d5d4cce669b6
doc/configuration.txt configuration.txt-20060314161707-868350809502af01
-------------- next part --------------
=== added file 'doc/bug_trackers.txt'
--- a/doc/bug_trackers.txt 1970-01-01 00:00:00 +0000
+++ b/doc/bug_trackers.txt 2007-07-13 22:35:07 +0000
@@ -0,0 +1,78 @@
+============
+Bug Trackers
+============
+
+Bazaar has a facility that allows you to associate a commit with a bug
+in the project's bug tracker. Other tools can then use this information
+to link between the commit and the bug, or to automatically mark the bug
+closed in the branches that contain the commit.
+
+Associating Commits and Bugs
+============================
+
+When you make a commit you can assiociate it with a bug by using the
+``--fixes`` option of ``commit``. For example::
+
+ $ bzr commit --fixes 12345 -m 'Properly close the connection on errors'
+
+This will set a revision property on the revision that is committed
+which contains the URI at which more information on the bug can be found.
+Bazaar itself does no more than this, but once the information is recorded
+other tools can make use of it.
+
+Configuration of the Bug Tracker
+================================
+
+As each project has it's own bug tracker, and there are many different
+bug tracking systems you must first do some configuration before you
+can use this system.
+
+Bazaar currently implements support for projects that use Bugzilla or
+Trac to manage their bugs. If your project uses a different system it
+is easy to add support for the system, perhaps through a plugin.
+
+If you do use Bugzilla or Trac then you only need to set a configuration
+variable which contains the base URL of the bug tracker. These options
+can go into ``bazaar.conf``, ``branch.conf`` or into a branch-specific
+configuration section in ``locations.conf``.
+
+You can set up these values for each of the projects you work on in
+``bazaar.conf``, as you specify a short name for each so that you
+can specify which you mean at commit time.
+
+bugzilla_<tracker_abbreviation>_url
+-----------------------------------
+If present, the location of the Bugzilla bug tracker referred to by
+<tracker_abbreviation>. This option can then be used together with ``bzr commit
+--fixes`` to mark bugs in that tracker as being fixed by that commit. For
+example::
+
+ bugzilla_squid_url = http://www.squid-cache.org/bugs
+
+would allow ``bzr commit --fixes squid:1234`` to mark Squid's bug 1234 as
+fixed.
+
+trac_<tracker_abbrevation>_url
+------------------------------
+If present, the location of the Trac instance referred to by
+<tracker_abbreviation>. This option can then be used together with ``bzr commit
+--fixes`` to mark bugs in that tracker as being fixed by that commit. For
+example::
+
+ trac_twisted_url = http://www.twistedmatrix.com/trac
+
+would allow ``bzr commit --fixes twisted:1234`` to mark Twisted's bug 1234 as
+fixed.
+
+Limitations of the system
+=========================
+
+This method of associating revisions and bugs does have some limitations. The
+first is that the association can only be made at commit time. This means that
+if you forget to make the association when you commit, or the bug is reported
+after you fix it you cannot go back and add the link later.
+
+Related to this is the fact that the association is immutable. If a bug is
+marked as fixed by one commit, but that revision does not fully solve the
+bug, or there is a later regression you cannot go back and remove the link.
+
=== modified file 'doc/README.1st'
--- a/doc/README.1st 2006-07-30 06:52:39 +0000
+++ b/doc/README.1st 2007-07-13 22:35:07 +0000
@@ -29,3 +29,7 @@
using_aliases.txt
How to setup and use command aliases.
+bug_trackers.txt
+ How to allow revisions to be associated with the bugs that they try
+ and fix in the project's bug tracking system.
+
=== modified file 'doc/configuration.txt'
--- a/doc/configuration.txt 2007-07-12 11:44:08 +0000
+++ b/doc/configuration.txt 2007-07-16 19:55:36 +0000
@@ -4,17 +4,22 @@
Information on how to configure Bazaar.
-
.. TODO: Should have some explanation of why you'd want things in
.. branch.conf.
-Location of configuration file
-==============================
+Location of configuration files
+===============================
Each user gets a pair of configurations files in ``$HOME/.bazaar``. The first
one, named ``bazaar.conf``, includes default configuration options. The other
file, ``locations.conf``, contains configuration information for specific
branch locations. These files are sometimes referred to as ``ini files``.
+Each branch can also contain a configuration file that sets values specific
+to that branch. This file is found at ``.bzr/branch/branch.conf`` within the
+branch. This file is visible to all users of a branch, if you wish to override
+one of the values for a branch with a setting that is specific to you then you
+can do so in ``locations.conf``.
+
General Format
==============
An ini file has three types of contructs: section headers, section
@@ -46,7 +51,6 @@
[/home/jdoe/branches/]
-
Section Variables
-----------------
@@ -132,7 +136,7 @@
editor
------
The path of the editor that you wish to use if *bzr commit* is run without
-a commit log message. This setting is trumped by the environment variable
+a commit message. This setting is trumped by the environment variable
``$BZR_EDITOR``, and overrides ``$VISUAL`` and ``$EDITOR``.
check_signatures
@@ -193,6 +197,8 @@
----------------------------
User and password to authenticate to the SMTP server. If smtp_username
is set, and smtp_password is not, Bazaar will prompt for a password.
+These settings are only needed if the SMTP server requires authentication
+to send mail.
Branch 6 Options
@@ -213,7 +219,7 @@
---------------
If present, the location of the default branch for pull or merge.
This option is normally set by ``pull --remember`` or ``merge
---remember``
+--remember``.
push_location
-------------
@@ -230,33 +236,3 @@
If set to "True", the branch should act as a checkout, and push each commit to
the bound_location. This option is normally set by ``bind``/``unbind``.
-
-Bug Tracker Options
-===================
-
-These options can go into bazaar.conf, branch.conf or into a branch-specific
-configuration section in locations.conf.
-
-bugzilla_<tracker_abbreviation>_url
------------------------------------
-If present, the location of the Bugzilla bug tracker referred to by
-<tracker_abbreviation>. This option can then be used together with ``bzr commit
---fixes`` to mark bugs in that tracker as being fixed by that commit. For
-example::
-
- bugzilla_squid_url = http://www.squid-cache.org/bugs
-
-would allow ``bzr commit --fixes squid:1234`` to mark Squid's bug 1234 as
-fixed.
-
-trac_<tracker_abbrevation>_url
-------------------------------
-If present, the location of the Trac instance referred to by
-<tracker_abbreviation>. This option can then be used together with ``bzr commit
---fixes`` to mark bugs in that tracker as being fixed by that commit. For
-example::
-
- trac_twisted_url = http://www.twistedmatrix.com/trac
-
-would allow ``bzr commit --fixes twisted:1234`` to mark Twisted's bug 1234 as
-fixed.
=== modified file 'doc/http_smart_server.txt'
--- a/doc/http_smart_server.txt 2007-03-02 12:40:45 +0000
+++ b/doc/http_smart_server.txt 2007-07-13 22:39:36 +0000
@@ -8,6 +8,11 @@
This document describes one way to set up a Bazaar HTTP smart server,
using Apache 2.0 and FastCGI or mod_python.
+For more information on the smart server, and other ways to configure it
+see the main `smart server documentation`_.
+
+.. _smart server documentation: server.htm
+
Example
=======
=== modified file 'doc/plugins.txt'
--- a/doc/plugins.txt 2007-03-02 12:40:45 +0000
+++ b/doc/plugins.txt 2007-07-13 22:44:26 +0000
@@ -20,6 +20,37 @@
=====================
We keep our list of plugins on the http://bazaar-vcs.org/BzrPlugins page.
+How to Install a plugin
+=======================
+Installing a plugin is very easy! One can either install a plugin
+system-wide or on a per user basis. Both methods involve creating a
+``plugins`` directory. Within this directory one can place plugins in
+subdirectories. For example, ``plugins/bzrtools/``.
+
+Two locations are currently checked: the bzrlib/plugins directory
+(typically found in ``/usr/lib/python2.4/site-packages/bzrlib/plugins/``) and
+``$HOME/.bazaar/plugins/``.
+
+One can additionally override the home plugins by setting the environment
+variable ``BZR_PLUGIN_PATH`` to a directory that contains plugins. The
+installation of a plugin can be checked by running ``bzr plugins`` at
+any time. New commands can be seen by running ``bzr help commands``.
+The commands provided by a plugin are shown followed by the name of the
+plugin in brackets.
+
+Plugins work particularly well with Bazaar branches. For example, to
+install the bzrtools plugins for your main user account, one can perform
+the following::
+
+ bzr branch http://panoramicfeedback.com/opensource/bzr/bzrtools
+ ~/.bazaar/plugins/bzrtools
+
+When installing plugins the directories that you install them in must
+be valid python identifiers. This means that they can only contain
+certain characters, notably they cannot contain hyphens (``-``). Rather
+than installing ``bzr-gtk`` to ``~/.bazaar/plugins/bzr-gtk``, install it
+to ``~/.bazaar/plugins/gtk``.
+
Writing a plugin
================
Plugins are very similar to bzr core functionality. They can import
@@ -47,26 +78,3 @@
Please feel free to contribute your plugin to BzrTools, if you think it
would be useful to other people.
-How to Install a plugin
-=======================
-Installing a plugin is very easy! One can either install a plugin
-system-wide or on a per user basis. Both methods involve creating a
-``plugins`` directory. Within this directory one can place plugins in
-subdirectories. For example, ``plugins/bzrtools/``.
-
-Two locations are currently checked: the bzrlib/plugins directory
-(typically found in ``/usr/lib/python2.4/site-packages/bzrlib/plugins/``) and
-``$HOME/.bazaar/plugins/``.
-
-One can additionally override the home plugins by setting the environment
-variable ``BZR_PLUGIN_PATH`` to a directory that contains plugins. The
-installation of a plugin can be checked by running ``bzr plugins`` at
-any time. New commands can be seen by running ``bzr help commands``.
-
-Plugins work particularly well with Bazaar branches. For example, to
-install the bzrtools plugins for your main user account, one can perform
-the following::
-
- bzr branch http://panoramicfeedback.com/opensource/bzr/bzrtools
- ~/.bazaar/plugins/bzrtools
-
More information about the bazaar-commits
mailing list