← Back to branch summary

~bzr/ubuntu/lucid/bzr/beta-ppa

« back to all changes in this revision

Viewing changes to doc/en/admin-guide/hooks-plugins.txt

  • Committer: Martin Pool
  • Date: 2010-07-02 07:29:40 UTC
  • mfrom: (129.1.7 packaging-karmic)
  • Revision ID: mbp@sourcefrog.net-20100702072940-hpzq5elg8wjve8rh
http://bugs.debian.org/452024
http://bugs.debian.org/464688
http://bugs.debian.org/523595
http://bugs.debian.org/526233
http://bugs.debian.org/537708
http://bugs.debian.org/555336
http://bugs.debian.org/555343
https://launchpad.net/bugs/249452
https://launchpad.net/bugs/385074
* PPA rebuild.
* PPA rebuild for Karmic.
* PPA rebuild for Jaunty.
* PPA rebuild for Hardy.
* From postinst, actually remove the example bash completion scripts.
  (LP: #249452)
* New upstream release.
* New upstream release.
* New upstream release.
* Revert change to Build-depends: Dapper does not have python-central.
  Should be python-support..
* Target ppa..
* Target ppa..
* Target ppa..
* Target ppa..
* New upstream release.
* Switch to dpkg-source 3.0 (quilt) format.
* Bump standards version to 3.8.4.
* Remove embedded copy of python-configobj. Closes: #555336
* Remove embedded copy of python-elementtree. Closes: #555343
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* debian/control: Fix obsolete-relation-form-in-source
  lintian warning. 
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split out docs into bzr-doc package.
* New upstream release.
* Added John Francesco Ferlito to Uploaders.
* Fix install path to quick-reference guide
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again, again.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to path changes.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Bump standards version to 3.8.3.
* Remove unused patch system.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix copy and paste tab error in .install file
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
 + Fixes compatibility with Python 2.4. Closes: #537708
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream version.
* Bump standards version to 3.8.2.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add python-pyrex to build-deps to ensure C extensions are always build.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix API compatibility version. (Closes: #526233)
* New upstream release.
  + Fixes default format for upgrade command. (Closes: #464688)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add missing dependency on zlib development library. (Closes:
  #523595)
* Add zlib build-depends.
* Add zlib build-depends.
* Add zlib build-depends.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Move to section vcs.
* Bump standards version to 3.8.1.
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Recommend ca-certificates. (Closes: #452024)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Update watch file. bazaar now uses launchpad to host its sources.
* Remove patch for inventory root revision copy, applied upstream.
* New upstream release.
* New upstream release.
* New upstream release
* Force removal of files installed in error to /etc/bash_completion.d/
  (LP: #249452)
* New upstream release.
* New upstream release
* New upstream release.
* Bump standards version.
* Include patch for inventory root revision copy, required for bzr-svn.
* New upstream release.
* Remove unused lintian overrides.
* Correct the package version not to be native.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Final 1.5 release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add myself as a co-maintainer.
* Add a Dm-Upload-Allowed: yes header.
* New upstream bugfix release.
* New upstream release.
* Final 1.3 release.
* New upstream release.
* First release candidate of the upcoming 1.3 release.
* Rebuild to fix the problem caused by a build with a broken python-central.
* New upstream release.
* Rebuild for dapper PPA.
* Apply Lamont's patches to fix build-dependencies on dapper.
  (See: https://bugs.launchpad.net/bzr/+bug/189915)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/admin-guide/hooks-plugins.txt
 
1
Extending Bazaar with Hooks and Plugins
 
2
=======================================
 
3
 
 
4
Bazaar offers a powerful extension mechanism for adding capabilities.  In
 
5
addition to offering full library API access to all of its structures, which
 
6
can be useful for outside programs that would like to interact with Bazaar
 
7
branches, Bazaar can also load *plugins* that perform specific tasks.  These
 
8
specific tasks are specified by *hooks* that run during certain steps of the
 
9
version control process.  
 
10
 
 
11
For full documentation on the available hooks, see ``bzr help hooks``.  Among
 
12
those, some of the most significant hooks from an administration
 
13
standpoint are `pre_commit`, `post_commit` and `post_change_branch_tip`.
 
14
A `pre_commit` hook can inspect a commit before it happens and cancel it if
 
15
some criteria are not met.  This can be useful for enforcing policies about
 
16
the code, such as line-endings or whitespace conventions.  A
 
17
`post_commit` hook can take actions based on the commit that just happened,
 
18
such as providing various types of notifications.  Finally, a
 
19
`post_change_branch_tip` hook is a more general form of a `post_commit`
 
20
hook which is used whenever the tip of a branch changes (which can happen in
 
21
more ways than just committing).  This too can be used for notification
 
22
purposes, as well as for backups and mirroring.
 
23
 
 
24
Information on the whole range of Bazaar plugins is available at
 
25
http://doc.bazaar.canonical.com/plugins/en/.  For purposes of installation,
 
26
plugins are simply python packages.  They can be installed alongside Bazaar in
 
27
the ``bzrlib.plugins`` package using each plugin's ``setup.py``.  They can
 
28
also be installed in the plugin path which is the user's ``~/.bazaar/plugins``
 
29
directory or can be specified with the ``BZR_PLUGIN_PATH`` environment
 
30
variable.  See ``bzr help configuration`` for more on specifying the location
 
31
of plugins.
 
32
 
 
33
 
 
34
Email Notification
 
35
------------------
 
36
 
 
37
A common need is for every change made on a branch to send an email message to
 
38
some address, most often a mailing list.  These plugins provide that capability
 
39
in a number of different ways.  
 
40
 
 
41
The `email` plugin sends email from each individual developer's computer.  This
 
42
can be useful for situations that want to track what each individual developer
 
43
is working on.  On the downside, it requires that every developer's branches be
 
44
configured individually to use the same plugin.  
 
45
 
 
46
The next two plugins `hookless-email` and `email-notifier` address this concern
 
47
by running on a central server whenever changes happen on centrally stored
 
48
branches.
 
49
 
 
50
email
 
51
~~~~~
 
52
 
 
53
To configure this plugin, simply install the plugin and configure the
 
54
``post_commit_to``  option for each branch.  This configuration can be done
 
55
in the ``locations.conf`` file or individually in each branch's
 
56
``branch.conf`` file.  The sender's email address can be specified as
 
57
``post_commit_sender`` if it is different than the email address reported by
 
58
``bzr whoami``.  The ``post_commit_mailer`` option specifies how the
 
59
mail should be sent.  If it isn't set, email is sent via ``/usr/bin/mail``.
 
60
It can also be configured to communicate directly with an SMTP server.
 
61
For more details on configuring this plugin, see
 
62
http://doc.bazaar-vcs.org/plugins/en/email-plugin.html.  As examples, consider
 
63
the following two possible configurations.  A minimal one (uses
 
64
``/usr/bin/mail``)
 
65
 
 
66
::
 
67
 
 
68
  [DEFAULT]
 
69
  post_commit_to = projectx-commits@example.com
 
70
 
 
71
and a more complicated one (using all of the options)
 
72
 
 
73
::
 
74
 
 
75
  [DEFAULT]
 
76
  post_commit_url = http://www.example.com/code/projectx/trunk
 
77
  post_commit_to = projectx-commits@example.com
 
78
  post_commit_sender = donotreply@example.com
 
79
  post_commit_mailer = smtplib
 
80
  smtp_server = mail.example.com:587
 
81
  smtp_username = bob
 
82
  # smtp_password = 'not specified, will prompt'
 
83
 
 
84
 
 
85
hookless-email
 
86
~~~~~~~~~~~~~~
 
87
 
 
88
This plugin is basically a server-side version of the `email` plugin.  It is
 
89
a program that runs either from the command line or as a daemon that monitors
 
90
the branches specified on the command line for any changes.  When a change
 
91
occurs to any of the monitored branches, it will send an email to the
 
92
specified address.  Using our simple example, the following command would send
 
93
an email to ``projectx-commits@example.com`` on any of the branches under
 
94
``/srv/bzr`` since the last time the command was run.  (This command could be
 
95
set up to run at regular intervals, for example from ``cron``.)
 
96
 
 
97
::
 
98
 
 
99
  $ bzr_hookless_email.py --email=projectx-commits@example.com \
 
100
  --recurse /srv/bzr
 
101
 
 
102
email-notifier
 
103
~~~~~~~~~~~~~~
 
104
 
 
105
This is a more elaborate version of the `hookless-email` plugin that can send
 
106
templated HTML emails, render wiki-style markup in commit messages and update
 
107
working copies on the server (similar to `push_and_update`_).  It can also
 
108
send emails reporting the creation of new branches or the removal of branches
 
109
under a specified directory (here ``/srv/bzr/projectx``).  As it is more
 
110
complicated, its configuration is also more complicated and we won't repeat
 
111
its documentation here, but a simple configuration that will send emails on
 
112
commits and creation/deletion of branches is
 
113
 
 
114
::
 
115
 
 
116
  [smtp]
 
117
 
 
118
  server=smtp.example.com
 
119
  # If user is not provided then no authentication will be performed.
 
120
  user=bob
 
121
  password=pAssW0rd
 
122
 
 
123
  [commits]
 
124
 
 
125
  # The address to send commit emails to. 
 
126
  to=projctx-commits@example.com
 
127
  from=$revision.committer
 
128
 
 
129
  # A Cheetah template used to construct the subject of the email message.
 
130
  subject=$relative_path: $revision_number $summary
 
131
 
 
132
  [new-branches]
 
133
  to=projectx-commits@example.com
 
134
  from=donotreply@example.com
 
135
  subject=$relative_path: New branch created
 
136
 
 
137
  [removed-branches]
 
138
  to=projectx-commits@example.com
 
139
  from=donotreply@example.com
 
140
  subject=$relative_path: Branch removed
 
141
 
 
142
If this file is stored as ``/srv/bzr/email-notifier.conf``, then the command
 
143
 
 
144
::
 
145
 
 
146
  $ bzr-email-notifier.py --config=/srv/bzr/email-notifier.conf /srv/bzr/projectx
 
147
 
 
148
will watch all branches under the given directory for commits, branch
 
149
creations and branch deletions.
 
150
  
 
151
 
 
152
Feed Generation
 
153
---------------
 
154
 
 
155
A related concept to sending out emails when branches change is the generation
 
156
of news feeds from changes on each branch.  Interested parties can then choose
 
157
to follow those news feeds in order to see what is happening on a branch.
 
158
 
 
159
branchfeed
 
160
~~~~~~~~~~
 
161
 
 
162
This plugin creates an ATOM feed for every branch on every branch change
 
163
(commit, etc.).  It stores these files as ``.bzr/branch/branch.atom`` inside
 
164
each branch.  Currently, it includes the 20 most recent changes in each feed.
 
165
To use it, simply install the plugin and set your feed reader to follow the
 
166
``branch.atom`` files.
 
167
 
 
168
In addition, there are other tools that are not plugins for creating news
 
169
feeds from Bazaar branches.  See http://bazaar-vcs.org/FeedGenerators for more
 
170
on those tools.
 
171
 
 
172
Mirroring
 
173
---------
 
174
 
 
175
Sometimes it is useful to ensure that one branch exists as an exact copy of
 
176
another.  This can be used to provide simple backup facilities or redundancy
 
177
(see `Back-up and restore <backup.html>`_ for more details on backups).  One
 
178
way to do this using Bazaar's workflows is to make the branch where changes
 
179
happen into a bound branch of the mirror branch.  Then, when commits happen on
 
180
the working branch, they will also happen on the mirror branch.  Note that
 
181
commits to bound branches do *not* update the mirror branch's working copy, so
 
182
if the mirror branch is more than just a backup of the complete history of the
 
183
branch, for example if it is being served as a web page, then additional
 
184
plugins are necessary.
 
185
 
 
186
push_and_update
 
187
~~~~~~~~~~~~~~~
 
188
 
 
189
This plugin updates Bazaar's ``push`` command to also update the remote
 
190
working copy.  It can only work over connections that imply filesystem or SSH
 
191
access to the remote working copy (``bzr+ssh://``, ``sftp://`` and
 
192
``file://``).  Also, it is only useful when the remote branch is updated with
 
193
an explicit ``push`` command.
 
194
 
 
195
automirror
 
196
~~~~~~~~~~
 
197
 
 
198
This plugin is similar to `push_and_update` in that it updates the working
 
199
copy of a remote branch.  The difference is that this plugin is designed to
 
200
update the remote branch on every change to the working branch.  To configure
 
201
this, set the ``post_commit_mirror = URL`` option on a branch.  This option
 
202
can include multiple branch URLs separated by commas to create multiple
 
203
mirrors.  For example, if we want to mirror our ``/srv/bzr/projectx/trunk``
 
204
branch to the URL ``sftp://www.example.com/var/www/projectx`` (for example if
 
205
ProjectX were a web project that we wanted to access at
 
206
``http://www.example.com/projectx``), then we could include
 
207
 
 
208
::
 
209
 
 
210
  [DEFAULT]
 
211
  post_commit_mirror = sftp://www.example.com/var/www/branches/trunk
 
212
 
 
213
in the file ``/srv/bzr/projectx/trunk/.bzr/branch/branch.conf``.
 
214
 
 
215
 
 
216
Other Useful Plugins
 
217
--------------------
 
218
 
 
219
pqm (plugin)
 
220
~~~~~~~~~~~~
 
221
 
 
222
Facilitating interaction with `PQM
 
223
<integration.html#patch-queue-manager-pqm>`_, this plugin provides support for 
 
224
submitting merge requests to a remote Patch Queue Manager.  PQM provides 
 
225
a way to automatically run the test suite before merging changes to the
 
226
trunk branch.
 
227
 
 
228
testrunner
 
229
~~~~~~~~~~
 
230
 
 
231
Sometimes referred to as the poor man's PQM, this plugin runs a single command
 
232
on the updated revision (in a temporary directory) and if the command returns
 
233
0, then the revision can be committed to that branch.  For example, if the
 
234
testsuite is run with the command ``nosetests`` in the root of the branch
 
235
(which returns 0 if the test suite passes and 1 if it doesn't pass), then one
 
236
can set 
 
237
 
 
238
::
 
239
 
 
240
  [DEFAULT]
 
241
  pre_change_branch_tip_test_command = nosetests
 
242
 
 
243
in ``.bzr/branch/branch.conf``.
 
244
 
 
245
checkeol
 
246
~~~~~~~~
 
247
 
 
248
This plugin is an example of a `pre_commit` hook that checks the revision
 
249
being committed for meeting some policy.  In this case, it checks that all of
 
250
the files have the specified line endings.  It uses a configuration file
 
251
``.bzreol`` in the root of the working tree (similar to the ``.bzrignore``
 
252
file).  This configuration file has sections for line feed endings (LF),
 
253
carriage return/line-feed endings (CRLF) and carriage return endings (CR).
 
254
For an unusual example that specifies different line endings for different
 
255
files, that file might look like
 
256
 
 
257
:: 
 
258
 
 
259
  [LF]
 
260
  *.py
 
261
  *.[ch]
 
262
 
 
263
  [CRLF]
 
264
  *.txt
 
265
  *.ini
 
266
 
 
267
  [CR]
 
268
  foo.mac
 
269
 
 
270
or if you simply want to enforce a single line ending convention on the branch
 
271
you can use
 
272
 
 
273
::
 
274
  
 
275
  [LF]
 
276
  *
 
277
 
 
278
This plugin needs to be installed on the server where the branch updates will
 
279
happen, and the ``.bzreol`` file must be in each branch where line ending
 
280
policies will be enforced.  (Adding it to the branch with ``bzr add .bzreol``
 
281
is an easy way to ensure this, although it means that branches on the server
 
282
must have working trees.)
 
283
 
 
284
text_checker
 
285
~~~~~~~~~~~~
 
286
 
 
287
This plugin is a more advanced version of `checkeol` that can check such
 
288
coding style guidelines such as trailing whitespace, long lines and files that
 
289
don't end with a newline.  It is configured using Bazaar's built in rules
 
290
specification in ``BZR_HOME/rules`` (see ``bzr help rules`` for more
 
291
information.  For different types of undesired changes, you can specify
 
292
different types of actions.  For example
 
293
 
 
294
::
 
295
 
 
296
  [name NEWS README]
 
297
  trailing_whitespace=fail
 
298
  long_lines=warn
 
299
  newline_at_eof=ignore
 
300
 
 
301
  [name *.py]
 
302
  tabs=fail
 
303
  long_line_length=78
 
304
  long_lines=fail
 
305
  trailing_whitespace=fail
 
306
 
 
307
will prevent changes from adding new trailing whitespace to the specified
 
308
files and keep all python source files free of tabs and lines over 78
 
309
characters.  To commit while violating these rules, one can pass the
 
310
``--text-check-warn-only`` option to commit.