← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Vincent Ladeuil
  • Date: 2009-04-27 16:10:10 UTC
  • mto: (4310.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 4311.
  • Revision ID: v.ladeuil+lp@free.fr-20090427161010-7swfzeagf63cpixd
Fix bug #367726 by reverting some default user handling introduced
while fixing bug #256612.

* bzrlib/transport/ssh.py:
(_paramiko_auth): Explicitly use getpass.getuser() as default
user.

* bzrlib/transport/ftp/_gssapi.py:
(GSSAPIFtpTransport._create_connection): Explicitly use
getpass.getuser() as default user.

* bzrlib/transport/ftp/__init__.py:
(FtpTransport._create_connection): Explicitly use
getpass.getuser() as default user.

* bzrlib/tests/test_sftp_transport.py:
(TestUsesAuthConfig.test_sftp_is_none_if_no_config)
(TestUsesAuthConfig.test_sftp_doesnt_prompt_username): Revert to
None as the default user.

* bzrlib/tests/test_remote.py:
(TestRemoteSSHTransportAuthentication): The really offending one:
revert to None as the default user.

* bzrlib/tests/test_config.py:
(TestAuthenticationConfig.test_username_default_no_prompt): Update
test (and some PEP8).

* bzrlib/smtp_connection.py:
(SMTPConnection._authenticate): Revert to None as the default
user.

* bzrlib/plugins/launchpad/account.py:
(_get_auth_user): Revert default value handling.

* bzrlib/config.py:
(AuthenticationConfig.get_user): Fix doc-string. Leave default
value handling to callers.

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.canonical.com/plugins/en/email-plugin.html.  As examples,
63
 
consider 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
170
 
http://wiki.bazaar.canonical.com/FeedGenerators for more 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.