Rev 27: Documentation overhaul. in http://people.ubuntu.com/~robertc/baz2.0/plugins/email/trunk
Robert Collins
robertc at robertcollins.net
Sun Jul 8 01:05:12 BST 2007
At http://people.ubuntu.com/~robertc/baz2.0/plugins/email/trunk
------------------------------------------------------------
revno: 27
revision-id: robertc at robertcollins.net-20070708000511-4inxppi8822gy1b1
parent: robertc at robertcollins.net-20070628071347-dvytdwqg5dme0xrf
committer: Robert Collins <robertc at robertcollins.net>
branch nick: trunk
timestamp: Sun 2007-07-08 10:05:11 +1000
message:
Documentation overhaul.
modified:
README README-20051018071212-c081f89570802202
__init__.py __init__.py-20051018071212-f1765ec4521cab0b
=== modified file 'README'
--- a/README 2007-02-07 00:11:04 +0000
+++ b/README 2007-07-08 00:05:11 +0000
@@ -1,36 +1,27 @@
-This is a plugin to implement post commmit emails for bzr.
-This should eventually allow format specifiers.
-
-The plugin is activated by installing it (check it out to
-~/.bazaar/plugins/email - 'ls ~/.bazaar/plugins/email/__init__.py' should list
-a file), and then configure an address to send to as listed below.
-
-NB: If you are using a bzr release from before 0.15, you need to manually tell
-bzr about the commit action, by setting
-post_commit=bzrlib.plugins.email.post_commit in bazaar.conf or locations.conf.
-
-The address to sent to is read from 'post_commit_to' and the address to send
-from from 'post_commit_sender' (if not supplied defaults to standard bzr
-'email').
-
-If 'post_commit_url' is set, it is used instead of the branch URL
-(useful since in most cases, you commit to a private url, and you want
-the public HTTP url in the commit message).
-
-The option 'post_commit_mailer' can be used to override the name of
-the mail program to use. It should behave like /bin/mail, at minimum
-supporting the -s and -a options.
-
-Alternatively 'post_commit_mailer' can be set to 'smtplib' which will use
-python's smtplib to send the email directly. If you use 'smtplib' you can also
-configure the settings "smtp_server=host[:port]", "smtp_username=userid",
-"smtp_password". If "smtp_username" is set but "smtp_password" is not, you
-will be prompted for a password.
-Also, if using 'smtplib', the messages will be sent as a UTF-8 text message,
-with a 8-bit text diff attached (rather than all-as-one). Work has also been
-done to make sure usernames do not have to be ascii.
-
-By default, the diff for the commit will be included in the email, if the
-length is less than 1000 lines. This limit can be changed (for instance, to 0
-to disable the feature) by setting the option 'post_commit_difflimit' to the
-number of lines you wish it to be limited to.
+This is a plugin which implements post commmit emails for bzr.
+
+The plugin is activated by:
+ - installing it
+ - configuring an address to send emails to (see ``bzr help email``).
+
+Installation
+------------
+
+The simplest way to install it for a single user is to do
+``bzr checkout https://launchpad.net/bzr-email ~/.bazaar/plugins/email``.
+
+If you need to install it system wide, or are packing the plugin for non-source
+distribution (e.g. as a .deb or .rpm) then there is a setup.py file that should
+do the right thing when called with the values you use elsewhere when
+installing python softare.
+
+After installing it you can use 'bzr help email' for documentation (for bzr >=
+0.16), or read the docstring at the top of __init__.py (for bzr < 0.16)
+
+TODO
+----
+
+ - support format specifiers / email templates.
+
+
+
=== modified file '__init__.py'
--- a/__init__.py 2007-06-28 07:13:47 +0000
+++ b/__init__.py 2007-07-08 00:05:11 +0000
@@ -14,12 +14,46 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-"""Allow sending an email after a new commit.
-
-This plugin provides a 'post_commit' hook, which is used to send an email (like
-to a developer mailing list) with the basic contents of the change.
-
-See the README file for basic information on how to configure this plugin.
+"""Sending emails upon commit with informatiopn about the commit.
+
+To have bzr send an email you need to configure an address to send mail
+to for that branch. To do this set the configuration option ``post_commit_to``
+and the address to send the mail from is read from the configuration option
+``post_commit_sender`` (if not supplied defaults to the email address reported
+by ``bzr whoami``).
+
+By default, the diff for the commit will be included in the email, if the
+length is less than 1000 lines. This limit can be changed (for instance, to 0
+to disable the feature) by setting the configuration option
+'post_commit_difflimit' to the number of lines you wish it to be limited to.
+
+If you are using a bzr release from before 0.15, you need to manually tell
+bzr about the commit action, by setting
+post_commit=bzrlib.plugins.email.post_commit in bazaar.conf or locations.conf.
+
+The URL of the branch is determined from the following checks (in order):
+ - If the configuration value 'post_commit_url' is set, it is used.
+ - If the configuration value 'public_branch' is set, it is used.
+ - The URL of the branch itself.
+
+Setting public_branch is highly recommended if you commit via a protocol which
+has a pricate address (e.g. bzr+ssh but anonymous access might be bzr:// or
+http://).
+
+How emails are sent is determined by the value of the configuration option
+'post_commit_mailer':
+ - Unset: use ``/usr/bin/mail``.
+ - ``smtplib``: Use python's smtplib to send the mail. If you use 'smtplib' you
+ can also configure the settings "smtp_server=host[:port]",
+ "smtp_username=userid", "smtp_password". If "smtp_username" is set but
+ "smtp_password" is not, you will be prompted for a password.S
+
+ Also, if using 'smtplib', the messages will be sent as a UTF-8 text message,
+ with a 8-bit text diff attached (rather than all-as-one). Work has also been
+ done to make sure usernames do not have to be ascii.
+ - Any other value: Run the value expecting it to behave like ``/usr/bin/mail``
+ - in particular supporting the -s and -a options.
+
"""
@@ -29,6 +63,7 @@
% __name__)
+# These three are used during import: No point lazy_importing them.
from bzrlib import errors
from bzrlib.branch import Branch
from bzrlib.lazy_import import lazy_import
@@ -40,9 +75,9 @@
def post_commit(branch, revision_id):
+ """This is the post_commit hook that should get run after commit."""
if not use_legacy:
return
- """This is the post_commit hook that should get run after commit."""
_emailer.EmailSender(branch, revision_id, branch.get_config()).send_maybe()
More information about the bazaar-commits
mailing list