Just a Theory

By David E. Wheeler

Posts about SVN::Notify

Up for Adoption: SVN::Notify

I’ve kept my various Perl modules in a Subversion server run by my Bricolage support company, Kineticode, for many years. However, I’m having to shut down the server I’ve used for all my services, including Subversion, so I’ve moved them all to GitHub. As such, I no longer use Subversion in my day-to-day work.

It no longer seems appropriate that I maintain SVN::Notify. This has probably been my most popular modules, and I know that it’s used a lot. It’s also relatively stable, with few bug reports or complaints. Nevertheless, there certainly could be some things that folks want to add, like TLS support, I18N, and inline CSS.

Therefore, SVN::Notify is formally up for adoption. If you’re a Subversion users, it’s a great tool. Just look at this sample output. If you’d like to take over maintenance, make it even better, please get in touch. Leave a comment on this post, or @theory me on Twitter, or send an email.

PS: Would love it if someone also could take over activitymail, the CVS notification script from which SVN::Notify was derived — and which I have even less right to maintain, given that I haven’t used CVS in years.

Looking for the comments? Try the old layout.

More about…

The Future of SVN::Notify

This week, I imported pgTAP into GitHub. It took me a day or so to wrap my brain around how it’s all supposed to work, with generous help from Tekkub. But I’m starting to get the hang of it, and I like it. By the end of the day, I had sent push requests to Test::More and Blosxom Plugins. I’m well on my way to being hooked.

One of the things I want, however, is SVN::Notify-type commit emails. I know that there are feeds, but they don’t have diffs, and for however much I like using NetNewsWire to feed by political news addiction, it never worked for me for commit activity. And besides, why download the whole damn thing again, diffs and all (assuming that ever happens), for every refresh. Seems like a hell of a lot unnecessary network activity—not to mention actual CPU cycles.

So I would need a decent notification application. I happen to have one. I originally wrote SVN::Notify after I had already written activitymail, which sends noticies for CVS commits. SVN::Notify has changed a lot over the years, and now it’s looking a bit daunting to consider porting it to Git.

However, just to start thinking about it, SVN::Notify really does several different things:

  • Fetches relevant information about a Subversion event.
  • Parses that information for a number of different outputs.
  • Writes the event information into one or more outputs (currently plain text or XHTML).
  • Constructs an email message from the outputs
  • Sends the email message via a specified method (sendmail or SMTP).

For the initial implementation of SVN::Notify, this made a lot of sense, because it was doing something fairly simple. It was designed to be extensible by subclassing (successfully done by SVN::Notify::Config and SVN::Notify::Mirror), and, later, by output filters, and that was about it.

But as I think about moving stuff to Git, and consider the weaknesses of extensibility by subclassing (it’s just not pretty), I’m naturally rethinking this architecture. I wouldn’t want to have to do it all over again should some future SCM system come along in the future. So, following from a private exchange with Martijn Van Beers, I have some preliminary thoughts on how a hypothetical SCM::Notify (VCS::Notify?) module might be constructed:

  • A single interface for fetching SCM activity information. There could be any number of implementations, just as long as they all provided the same interface. There would be a class for fetching information from Subversion, one for Git, one for CVS, etc.
  • A single interface for writing a report for a given transaction. Again, there could be any number of implementations, but all would have the same interface: taking an SCM module and writing output to a file handle.
  • A single interface for doing something with one or more outputs. Again, they can do things as varied as simply writing files to disk, appending to a feed, inserting into a database, or, of course, sending an email.
  • The core module would process command-line arguments to determine what SCM is being used any necessary contextual information and just pass it on to the appropriate classes.

In psedudo-code, what I’m thinking is something like this:

package SCM::Notify;

sub run {
    my $args = shift->getopt;
    my $scm  = SCM::Interface->new(
        scm      => $args->{scm} # e.g., "SVN" or "Git", etc.
        revision => $args->{revision},
        context  => $args->{context} # Might include repository path for SVN.
    );

    my $report = SCM::Report->new(
        method => $opts->{method}, # e.g., SMTP, sendmail, Atom, etc.
        scm    => $scm,
        format => $args->{output}, # text, html, both, etc.
        params => $args->{params}, # to, from, subject, etc.
    );

    $report->send;
}

Then a report class just has to create report in the specified format or formats and do something with them. For example, a Sendmail report would put together a report as a multipart message with each format in a single part, and then deliver it via /sbin/sendmail, something like this:

package SCM::Report::Sendmail;

sub send {
    my $self = shift;
    my $fh = $self->fh;
    for my $format ( $self->formats ) {
        print $fh SCM::Format->new(
            format => $format,
            scm    => $self->scm,
        );
    }

    $self->deliver;
}

So those are my rather preliminary thoughts. I think it’d actually be pretty easy to port the logic of this stuff over from SVN::Notify; what needs some more thought is what the command-line interface might look like and how options are passed to the various classes, since the Sendmail report class will require different parameters than the SMTP report class or the Atom report class. But once that’s worked out in a way that can be handled neutrally, we’ll have a much more extensible implementation that will be easy to add on to going forward.

Any suggestions for passing different parameters to different classes in a single interface? Everything needs to be able to be handled via command-line options and not be ugly or difficult to use.

So, you wanna work on this? :-)

Looking for the comments? Try the old layout.

SVN::Notify 2.70: Output Filtering and Character Encoding

I’m very pleased to announce the release of SVN::Notify 2.70. You can see an example of its colordiff output here. This is a major release that I’ve spent the last several weeks polishing and tweaking to get just right. There are quite a few changes, but the two most important are improved character encoding support and output filtering.

Improved Character Encoding Support

I’ve had a number of bug reports regarding issues with character encodings. Particularly for folks working in Europe and Asia, but really for anyone using multibyte characters in their source code and log messages (and we all do nowadays, don’t we?), it has been difficult to find the proper incantation to get SVN::Notify to convert data from and to their proper encodings. Using a patch from Toshikazu Kinkoh as a starting-point, and with a lot of reading and experimentation, as well as regular and patient tests on Toshikazu’s and Martin Lindhe’s production systems, I think I’ve finally got it nailed down.

Now you can use the --encoding (formerly --charset), --svn-encoding, and --diff-encoding options—as well as --language—to get SVN::Notify to do the right thing. As long as your Subversion server’s OS supports an appropriate locale, you should be golden (mine is old, with no UTF-8 locales :\). And if all else fails, you can still set the $LANG environment variable before executing svnnotify.

There is actually a fair bit to know about encodings to get it to work properly, but if you use UTF-8 throughout and your OS supports UTF-8 locales, you shouldn’t have to do anything. You might have to set --language in order to get it to use the proper locale. See the new documentation of the encoding support for all the details. And if you still have problems, please do let me know.

Output Filtering

Much sexier is the addition of output filtering in SVN::Notify 2.70. I got pretty tired of getting feature requests for what are essentially formatting modifications, such as this one requesting support for KDE-style keyword support. I myself was using Trac wiki syntax in commit messages on a recent project and wanted to see them converted to HTML for messages output by SVN::Notify::HTML::ColorDiff.

So I finally sat down and gave some though on how to implement a simple plugin architecture for SVN::Notify. When I realized that it was generally just formatting that people wanted, it became simpler: I just needed a way to allow folks to write simple output filters. The solution I came up with was to just use Perl. Output filters are simply subroutines named for the kind of output they filter. They live in perl packages. That’s it.

For example, say that your developers write their commit log messages in Textile, and rather than receive them stuck inside <pre> tags, you’d like them converted to HTML. It’s simple. Just put this code in a Perl module file:

package SVN::Notify::Filter::Textile;
use Text::Textile ();

sub log_message {
    my ($notifier, $lines) = @_;
    return $lines unless $notify->content_type eq 'text/html';
    return [ Text::Textile->new->process( join $/, @$lines ) ];
}

Put the file, SVN/Notify/Filter/Textile.pm somewhere in a Perl library directory. Then use the new --filter option to svnnotify to put it to work:

svnnotify -p "$1" -r "$2" --handler HTML::ColorDiff --filter Textile

Yep, that’s it! SVN::Notify will find the filter module, load it, register its filtering subroutine, and then call it at the appropriate time. Of course, there are a lot of things you can filter; consult the complete documentation for all of the details. But hopefully this gives you a flavor for how easy it is to write new filters for SVN::Notify. I’m hoping that all those folks who want features can now stop bugging me and writing their own filters to do the job, and uploading them to CPAN for all to share!

To get things started, I scratched my own itch, writing a Trac filter myself. The filter is almost as simple as the Textile example above, but I also spent quite a bit of time tweaking the CSS so that most of the Trac-generated HTML looks good. You can see an example right here. Thanks to a number of bug fixes in Text::Trac, as well as Trac-specific CSS added via a filter on CSS output, it works beautifully. If I’m feeling motivated in the next week or so, I’ll create a separate CPAN distribution with just a Markdown filter and upload it. That will create a nice distribution example for folks to copy to create their own. Or maybe someone on the Lazy Web Will do it for me! Maybe you?

I wish I’d thought to do this from the beginning; it would have saved me from having to add so many features/cruft to SVN::Notify over the years. Here’s a quick list of the features that likely could have been implemented via filters instead of added to the core:

  • --user-domain: Combine the SVN username with a domain for the “From” header.
  • --add-header: Add a header to the message.
  • --reply-to: Add a specific header to the message.
  • SVN::Notify::HTML::ColorDiff: Frankly, looking back on it, I don’t know why I didn’t just put this support right into SVN::Notify::HTML. But even if I hadn’t, it could have been implemented via filters.
  • --subject-prefix:: Modify the message subject.
  • --subject-cx: Add the commit context to the subject.
  • --strip-cx-regex: More subject context modification.
  • --no-first-line: Another subject filter.
  • --max-sub-length: Yet another!
  • --max-diff-length: A filter could truncate the diff, although this might be tricky with the HTML formatting.
  • --author-url: Modify the metadata section to add a link to the author URL.
  • --revision-url: Ditto for the revision URL.
  • --ticket-map: Filter the log message for various ticketing system strings to convert to URLs. This also encompasses the old --rt-url, --bugzilla-url, --gnats-url, and --jira-url options.
  • --header: Filter the beginning of the message.
  • --footer: Filter the end of the message.
  • --linkize: Filter the log message to convert URLs to links for HTML messages.
  • --css-url: Filter the CSS to modify it, or filter the start of the HTML to add a link to an external CSS URL.
  • --wrap-log: Reformat the log message for HTML.

Yes, really! That’s about half the functionality right there. I’m glad that I won’t have to add any more like that; filters are a much better way to go.

So download it, install it, write some filters, get your multibyte characters output properly, and enjoy! And as usual, send me your [bug reports]let me know, but implement your own improvements using filters!

Looking for the comments? Try the old layout.

SVN::Notify 2.57 Supports Windows

So I finally got ‘round to porting SVN::Notify to Windows. Version 2.57 is making is way to CPAN right now. The solution turned out to be dead simple: I just had to use a different form of piping open() on Windows, i.e., open FH, "$cmd|" instead of open FH, "-|"; exec($cmd);. It’s silly, really, but it works. It really makes me wonder why -| and |- haven’t been emulated on Windows. Whatever.

‘Course the other thing I realized, after I made this change and all the tests pass, was that there is no equivalent of sendmail on Windows. So I added the --smtp option, so that now email can be sent to an SMTP server rather than to a local sendmail. I tested it out, and it seems to work, but I’d be especially interested to hear from folks using wide characters in their repositories: do they get printed properly to Net::SMTP’s connection?

The whole list of changes in 2.57 (the output remains the same as in 2.56):

  • Finally ported to Win32. It was actually a simple matter of changing how command pipes are created.
  • Added --smtp option to enable sending messages to an SMTP server rather than to the local sendmail application. This is essential for Windows support.
  • Added --io-layer to the usage statement in svnnotify.
  • Fixed single-dash arguments in documentation so that they’re all documented with a single dash in SVN::Notify.

Enjoy!

Looking for the comments? Try the old layout.

SVN::Notify 2.56 Adds Alternative Formats

I’ve just uploaded SVN::Notify 2.56 to CPAN. Check a mirror near you! There have been a lot of changes since I last posted about SVN::Notify (for the 2.50 release), not least of which is that SourceForge has standardized on it for their Subversion roll out. W00t! The result was a couple of patches from SourceForge’s David Burley to add headers and footers and to truncate diffs over a certain size. See the sample output for how it looks. Thanks, David!

The change I’m most pleased with in 2.56 is the addition of SVN::Notify::Alternative, based on a submission from Jukka Zitting. This new subclass allows you to actually combine a number of other subclasses into a single activity notification message. Why? Well, mainly because, though you might like to get HTML messages with colorized diffs, some mail clients might not care for the HTML. They would much prefer the plain text version.

SVN::Notify::Alternative allows you to have your cake and eat it too: send a single message with multipart/alternative sections for both HTML output and plain text. Plain text will always be used; to use HTML::ColorDiff with it, just do this:

svnnotify --repos-path "$1" --revision "$2" \
  --to developers@example.com --handler Alternative \
  --alternative HTML::ColorDiff --with-diff

This incantation will send an email with both the plain text and HTML::ColorDiff formats. If you look at it in Mail.app, you’ll see the nice colorized format, and if you look at it in pine, you’ll see the plain text.

For the curious, here are all of the changes since 2.50:

2.56 2006-04-04T23:16:37
  • Abstracted creation of the diff file handle into the new diff_handle() method.
  • Documented use of diff_handle() in the output() method.
  • Added optional second argument to output() to optionally suppress the output of the email headers. This argument is used by the new Alternative subclass.
  • Added SVN::Notify::Alternative, which allows multiple versions of a commit email to be sent, such as text/plain plus HTML. The multiple versions are assembled into a single email message using the multipart/alternative media type. For those who want HTML messages but must support users that can only read plain text or rely on archives that ignore HTML messages, this can be very useful. Based on an implementation by Jukka Zitting.
  • Fixed use_ok() tests that weren’t running at all.
  • Added an extra newline to separate the file list from an inline diff in the plain text format where --with-diff has been specified.
  • Moved the multipart/mixed content-type header generation from output_headers() to output_content_type(), not only because this makes more sense, but also because it makes attachments behave better when using SVN::Notify::Alternative.
  • Documented accessors in SVN::Notify::HTML.
2.55 2006-04-03T23:11:11
  • Added the io-layer option to specify an alternate IO layer. Will be most useful for those with repositories containing text in multiple encodings, where it should be set to “raw”.
  • Fixed the context output in the subject for the --subject-cx option so that it’s smarter about determining the longest common path. Reported by Max Horn.
  • No longer modifying the values of the to_regex_map hash, so as not to mess with folks who might be passing it as a hash to more than one call to new(). Reported by Darby Felton.
  • Added a meta http-equiv="content-type" tag to HTML output that includes the character set to help some clients in the proper display of the characters in an HTML email. I’m not sure if any clients actually need this help, but it certainly can’t hurt!
  • Added the --css-url option to specify an alternate style sheet for HTML emails. SVN::Notify::HTML’s own CSS is left in the email, as well, so the specified style sheet can just override the default, rather than have to style everything itself. Yes, it takes advantage of the “cascading” feature of cascading style sheets! Based on a suggestion by Steve James.
2.54 2006-03-06T00:33:42
  • Added /usr/bin to the list of paths searched for executables. Suggested by Nacho Barrientos.
  • Added --max-diff-length option. Patch from David Burley/SourceForge.
2.53 2006-02-24T21:30:48
  • Added header and footer attributes and command-line options to specify text to be put at the head and foot of each message. For HTML messages, the text will be escaped, unless it starts with “<”, in which case it will be assumed to be valid HTML and will therefore not be escaped. Either way, it will be output between <div> tags with the IDs “header” or “footer” as appropriate. Based on a patch from David Burley/SourceForge.
  • Fixed the executable-searching algorithm added in 2.52 to add “.exe” to the name of the executable being searched for if $^O eq 'MSWin32'.
  • Fixed encoding issues so that, under Perl 5.8 and later, the IO layer is set on file handles so as to encode input and decode output in the character set specified by the charset attribute. CPAN # 16050, reported by Michael Zehrer.
  • Added a second argument to all calls to encode_entities() in SVN::Notify::HTML and SVN::Notify::HTML::ColorDiff so that only ‘>’. ‘<’, ‘&‘, and ‘“’ are escaped.
  • Fixed a bug in the _find_exe() function that was attempting to modify a constant variable. Patch from John Peacock.
  • Turned the _find_exe() function into the find_exe() class method, since subclasses (such as SVN::Notify::Mirror) might want to use it.
2.52 2006-02-19T18:50:24
  • Now uses File::Spec->path to search for a validate sendmail or svnlook when they’re not specified via their respective command-line options or environment variables. Suggested by Andreas Koenig. Not that they should probably be explicitly set anyway, as the $PATH environment variable tends to be non-existent when running under Apache.
2.51 2006-01-02T23:28:11
  • Fixed ColorDiff HTML to once again be valid XHTML 1.1.

Enjoy!

Looking for the comments? Try the old layout.

More about…

Port SVN::Notify to Windows

So SVN::Notify doesn’t currently run on Windows. Why not? Well, because I wanted to do things as “rightly” as possible. In terms of efficiency, what that meant was, rather than slurping in whole chunks of data, such as diffs, from svnlook, I instead follows the guidance in perlipc to open a file handle pipe to svnlook and then read from it line-by-line. The method I wrote to create the pipe looks like this:

sub _pipe {
    my ($self, $mode) = (shift, shift);
    # Safer version of backtick (see perlipc(1)).
    local *PIPE;
    my $pid = open(PIPE, $mode);
    die "Cannot fork: $!\n" unless defined $pid;

    if ($pid) {
        # Parent process. Return the file handle.
        return *PIPE;
    } else {
        # Child process. Execute the commands.
        exec(@_) or die "Cannot exec $_[0]: $!\n";
        # Not reached.
    }
}

The problem is that it doesn’t work on Windows. perlipc says:

Note that these operations are full Unix forks, which means they may not be correctly implemented on alien systems. Additionally, these are not true multithreading. If you’d like to learn more about threading, see the modules file mentioned below in the SEE ALSO section.

‘Course, the SEE ALSO section doesn’t have much of for “alien systems,” but I have a comment in my code that suggests that Win32::Process might do for Windows compatibility. But I honestly don’t know.

So what’s the best approach for me to port SVN::Notify to Windows while keeping file handle pipes around for efficiency? Anyone care to take a stab at it, with tests for Winows, and send me a patch?

Looking for the comments? Try the old layout.

SVN::Notify 2.50

SVN::Notify 2.50 is currently making its way to CPAN. It has quite a number of changes since I last wrote about it here, most significantly the slick new CSS treatment introduced in 2.47, provided by Bill Lynch. I really like the look, much better than it was before. Have a look at the SVN::Notify::HTML::ColorDiff output to see what I mean. Be sure to make your browser window rally narrow to see how all of the sections automatically get a nice horizontal scrollbar when they’re wider than the window. Neat, eh? Check out the 2.40 output for contrast.

Here are all of the changes since the last version:

2.50 2005-11-10T23:27:22
  • Added --ticket-url and --ticket-regex options to be used by those who want to match ticket identifers for systems other than RT, Bugzilla, GNATS, and JIRA. Based on a patch from Andrew O’Brien.
  • Removed bogus use lib line put into Makefile.PL by a prerelease version of Module::Build.
  • Fixed HTML tests to match either “’” or “&#39;”, since HTML::Entities can be configured differently on different systems.
2.49 2005-09-29T17:26:14
  • Now require Getopt::Long 2.34 so that the --to-regex-map option works correctly when it is used only once on the command-line.
2.48 2005-09-06T19:14:35
  • Swiched from <span class="add"> and <span class="rem"> to <ins> and <del> elements in SVN::Notify::HTML::ColorDiff in order to make the markup more semantic.
2.47 2005-09-03T18:54:43
  • Fixed options tests to work correctly with older versions of Getopt::Long. Reported by Craig McElroy.
  • Slick new CSS treatment used for the HTML and HTML::ColorDiff emails. Based on a patch from Bill Lynch.
  • Added --svnweb-url option. Based on a patch from Ricardo Signes.
2.46 2005-05-05T05:22:54
  • Added support for “Copied” files to HTML::ColorDiff so that they display properly.
2.45 2005-05-04T20:38:18
  • Added support for links to the GNATS bug tracking system. Patch from Nathan Walp.
2.44 2005-03-18T06:10:01
  • Fixed Name in POD so that SVN::Notify’s POD gets indexed by search.cpan.org. Reported by Ricardo Signes.
2.43 2004-11-24T18:49:40
  • Added --strip-cx-regex option to strip out parts of the context from the subject. Useful for removing parts of the file names you might not be interested in seeing in every commit message.
  • Added --no-first-line option to omit the first sentence or line of the log message from the subject. Useful in combination with the --subject-cx option.
2.42 2004-11-19T18:47:20
  • Changed “Files” to “Paths” in hash returned by file_label_map() since directories can be listed as well as files.
  • Fixed SVN::Notify::HTML so that directories listed among the changed paths are not links.
  • Requiring Module::Build 0.26 to make sure that the installation works properly. Reported by Robert Spier.

Enjoy!

Looking for the comments? Try the old layout.

SVN::Notify 2.41 Adds Plain Text Issue Tracking Links

I expect that this will be my last release of SVN::Notify for a while. I’ve already spent more time on it than I had anticipated. But anyway, this is a pretty solid release. It doesn’t change the API or anything, but I feel that the jump from 2.30 to 2.40 is justified because of the sheer number of changes. From now on, I expect that it will mostly be maintenance, like 2.41, which fixes a minor formatting bug. Grab it now from CPAN.

First, I’ve added a new, complex example of the SVN::Notify::HTML::ColorDiff output that I will keep up-to-date with all future changes. This will allow people to get a better idea of what it’s capable of than my previous contrived examples allowed.

The biggest change is that I’ve moved the Request Tracker, Bugzilla, and JIRA support from SVN::Notify::HTML to SVN::Notify. I realized, after the release of 2.30, that it might be cool to add links to the text-only email message generated by SVN::Notify, too. So I’ve done that, including for ViewCVS links. Unlike in SVN::Notify::HTML, the links won’t be inline in the message (that doesn’t work too well in plain text, IMO), but will come in their own sections after the message. So you’ll get something like this (extreme example):

Log Message:
-----------
Let's try a few links to other applications. First, we have
A Bugzilla Bug # 709. Then we have a JIRA key, TST-1608. And
finally, we have an RT link to Ticket # 4321.

Hey, we could add one to ViewCVS for a Subversion Revision
#606, too!

ViewCVS Links:
-------------
    http://viewsvn.bricolage.cc/?rev=606&view=rev

Bugzilla Links:
--------------
    http://bugzilla.mozilla.org/show_bug.cgi?id=709

RT Links:
--------
    http://rt.cpan.org/NoAuth/Bugs.html?id=4321

JIRA Links:
----------
    http://jira.atlassian.com/secure/ViewIssue.jspa?key=TST-1608

The nice thing is that, for many mail clients, these will be turned into clickable links. You’ll also notice that the text that creates the ViewCVS link is split over two lines. This is new in this release, and works for SVN::Notify::HTML, too. I made a few other tweaks to the regular expressions, as well. Here’s a complete list of changes:

  • Fixed accessor generation so that accessors created for the attributes passed to register_attributes() but a subclass are created in the subclass’ package instead of in SVN::Notify.
  • Changed parsing for JIRA keys to use any set of capital letters followed by a dash and then a number, rather than the literal string “JIRA-” followed by a number. Reported by Garrett Rooney.
  • Modified the regular expression patterns for the RT, Bugzilla, RT, and ViewCVS links to properly match on word boundaries, so that strings like “humbug 12” don’t match.
  • Modified the ViewCVS link regular expression pattern so that it matches strings like “rev 12” as well as “revision 12”.
  • Modified the RT link regular expression pattern so that it matches strings like “RT-Ticket: 23” as well as “Ticket 1234”. Suggested by Jesse Vincent.
  • Added complicated example to try to show off all of the major features. I will keep this up-to-date going forward in order to post sample output on the Web.
  • Fixed the parsing of log messages so that empty lines are no longer eliminated.
  • HTML::ColorDiff now properly handles the listing of binary files in the diff, marking them with a new class, “binary”, and using the same CSS as is used for the “propset” class.
  • In HTML::ColorDiff, Fixed CSS for the “delfile” class to properly wrap it in a border like the other files in the diff.
  • Added labels to the HTML::ColorDiff diff file sections to indicate the type of change (“Modified”, “Added”, “Deleted”, or “Property changes”).
  • Moved the rt_url, bugzilla_url, and jira_url parameters from SVN::Notify::HTML to SVN::Notify, where they are used to add URLs to the text version of log messages.

Enjoy!

Looking for the comments? Try the old layout.

SVN::Notify 2.30 Adds Issue Tracking Links

I released a new version of SVN::Notify last night, 2.30. This new version has a few things going for it.

First, and most obviously from the point of view of users of the HTML subclass, I’ve added new options for specifying Request Tracker, Bugzilla, and JIRA URLs. The --rt-url, --bugzilla-url, and --jira-url options have an effect much like the parallel feature in CVSspam: pass in a string with the spot for the ID represented by %s, such as http://rt.cpan.org/NoAuth/Bugs.html?id=%s for RT or http://bugzilla.mozilla.org/show_bug.cgi?id=%s for Bugzilla. SVN::Notify::HTML will then look for the appropriate strings (such as “Ticket # 1234” for RT or “Bug # 4321” for Bugzilla) and turn them into URLs.

This functionality has been extended to the old --viewcvs-url option, to. For the sake of consistency, it now also requires a URL of the same form (although if SVN::Notify doesn’t see %s in the string, it will append a default and emit a warning), and will be used to create links for strings like “Revision 654” in the log message.

SVN::Notify::HTML has an additional new option, --linkize, that will force any email addresses or URLs it finds in the log message to be turned into links. Again, this works like it does for CVSspam; I’m grateful to Jeffrey Friedl’s Mastering Regular Expressions, Second Edition for the excellent regular expressions for matching URLs and email addresses.

All of this was made possible by moving the processing of options from svnnotify to SVN::Notify->get_options and adding a new class method, SVN::Notify->register_attributes. This second method allows Bricolage subclasses to easily add new attributes; register_attributes() will create accessor methods and add command-line option processing for each new attribute required by a subclass. Then, when you execute svnnotify --handler HTML, SVN::Notify->get_options processes the default options, loads the SVN::Notify::Handler subclass, and then processes any options specified by the subclass. The short story is that all of this is the detail-oriented way of saying that it is easier to subclass SVN::Notify and be able to automatically load the necessary options and attributes via the same executable, svnnotify.

This change was motivated not only by my desire to add the new features to SVN::Notify::HTML, but also by Autrijus’ new modules, SVN::Notify::Snapshot and SVN::Notify::Config. Thanks Autrijus!

I’ll try to get a nice example of all this functionality up in the next few days; if anyone else creates one first, send it to me! But in the meantime, enjoy!

Looking for the comments? Try the old layout.

SVN::Notify 2.22 Improves Diff Parsing

I released SVN::Notify 2.22 last night. The new version fixes a few issues in the parsing of diffs in the HTML subclasses. SVN::Notify::HTML now properly identifies added, deleted, and property setting sections of an included diff file when creating IDs. The lists of the affected files near the top of the email links down into the diff, and now also includes links to the locations in the diff for files that have had only their properties changed.

SVN::Notify::HTML::ColorDiff had similar updates. It now properly outputs added and deleted files in the diff in separate sections, instead of grouping them under the last modified file listed. It also creates separate sections for files that have only had their properties changed. I’ve put an example here.

Grab the new version from CPAN now

Looking for the comments? Try the old layout.

SVN::Notify 2.20 Adds Colorized Diffs

After getting prodded by Erik Hatcher, I went ahead and added another subclass to SVN::Notify. This one adds a pretty colorized diff to the message, instead of just the plain text one. See an example here. I’ve also added links from the lists of affected files into the diffs in the HTML and new HTML::ColorDiff layouts.

Enjoy!

Update: And now I’ve released SVN::Notify 2.21 with a few minor fixes, including XHTML 1.1 compliance.

Looking for the comments? Try the old layout.

SVN::Notify 2.10 Generalizes Behavior

It’s all Autrijus’ fault.

As I mentioned last week when I released SVN::Notify 2.0, Autrijus has suggested using SVN::Notify as the base class for modules that do other things, such as send instant messages or update a checkout for backup purposes. Instantly seeing the value in this, I further realized that I could greatly simplify the support for HTML notification emails by moving the HTML-specific code to a subclass and then just let polymorphism do the work.

The result SVN::Notify 2.10. To simplify the move to a subclass for the HTML notifications, I broke up the old send() method into a large number of other methods that affect various parts of the composition of the email, such as headers, starting the message, outputting the log message, the file list, and outputting or attaching the diff. Then I just overrode the few methods that need different behavior in the subclass, and it all worked!

I realized, as I worked on it, I also realized that I was following the same principals that Ovid has written about with regard to the use of if. I was able to remove quite a few of them by moving HTML to a subclass. Of course, there are still some to enable diffs to be either included in an email or attached, but I didn’t want to split things up too much, or I’d have a geometric explosion of subclasses!

The svnnotify script, in the meantime, remains largely unmodified. The only change is the deprecation of the --format option in favor of a new option, --handler. Use this option to specify what subclass of SVN::Notify should handle the notification. So far, there’s just one, --format HTML, but I’m sure that Autrijus will soon add --format Jabber, and I’d like to add --format HTML::ColorDiff, myself. I might have to move the processing of command-line arguments out of svnnotify and into SVN::Notify, instead, so that subclasses can add new options. We’ll see what comes up.

Other changes to SVN::Notify include:

  • Added code to Build.PL to set the shebang line in the test scripts. Reported by Robert Spier.
  • Changed name of attached diff file to be named for the revision and the committer, rather than the committer and the date. Suggested by Robert Spier.
  • Added Author, Date, and Revision information to the top of each message.
  • The ViewCVS URL is no longer output for each file. A single link for the entire revision number is put at the top of the email, instead. ViewCVS Revision URL syntax pointed out by Peter Valdemar Morch.
  • Changed the send() method to execute() to better reflect its generalized use as the method that executes actions in response to Subversion activity.
  • The tests no longer require HTML::Entities to run. The HTML email tests will be skipped if it is not installed.
  • Added accessor methods for the attributes of SVN::Notify.

Enjoy!

Looking for the comments? Try the old layout.

SVN::Notify 2.0 Hitting CPAN

My latest Perl module, SVN::Notify 2.00, has hit CPAN. This is a port of my widely-used activitymail CVS notification script to Subversion. But it underwent quite a few changes over the port, including:

Modularization
The old monolithic activitymail script is gone. It has been replaced with a Perl class, SVN::Notify, that does most of the work. The new script, svnnotify, is essentially just a wrapper around the class; all it does is process command-line arguments and then pass the results to SVN::Notify.
Simplification
Subversion’s system for hooking in to commit transactions is far better thought-out than that of CVS. It’s now easy to capture the results of an entire commit in a single transaction, without having to write out temp files to keep track of where we are and to concatenate diffs. As a result, SVN::Notify has a much simpler architecture and implementation that requires fewer third-party modules to do its work. In addition, the move to a class should make it much easier to build on SVN::Notify in the future than it was with activitymail. Autrijus Tang already suggested a number of ideas on IRC, including SVN::Notify::Jabber or SVN::Notify::Export. Have at it, everyone!
Reduced Resource Usage
I had heard some complaints that, on very large commits, activitymail could end up taking up a huge amount of memory. As best I could figure, this was because it was loading everything into memory, including the diff for the commit! SVN::Notify avoids this problem by using a file handle to read in a diff an print it to sendmail one line at a time. This should keep resource usage by SVN::Notify way below what activitymail used.
Context-Specific Notifications
SVN::Notify has added support for mapping email addresses to regular expressions. Whenever a regular expression matches the name of one or more of the directories affected in a single commit, the corresponding email address will be added to the list of recipients of the notification. This is a great way to get notification messages sent to particular email addressed based on what part of the Subversion tree was affected by a commit. I intend to use this to set it up so that a list of translators only get notification about a commit when it changes a directory related to localization in my projects, so that they can ignore commits to other parts of the application.

These are the major changes, but SVN::Notify also features a number of smaller improvements over its activitymail ancestor, including character set support, user domain support for the “From” header, explicit specification of a “From” header, properly escaped content when sending HTML-formatted notifications, and a maximum subject length configuration.

So what did it lose? Just a few things:

  • syncmail-like behavior. Did anyone ever use this? If so, feel free to implement SVN::Notify::Syncmail.
  • Arguments to diff. SVN::Notify just uses svnlook diff to generate a diff. Support for other diffs could be added in a future version, if people really need it.
  • New directories and imports can no longer be ingored, because in Subversion they’re really no different from any other commit.
  • Limit on the maximum size of the email. This is because SVN::Notify no longer loads the entire email into memory to measure it.
  • Excluding certain files from the diff. Subversion handles this itself by paying attention to the media type of each file.
  • Windows support. Actually, I’m not sure if activitymail was ever used on Windows, but the new method of using pipes to communicate with other processes isn’t supported by Windows, as near as I can tell. There are comments in the code for those who wish to do the port; it would probably be easy using Win32::Process.

Not too much, eh? Let me know what you think, and send feedback!

Looking for the comments? Try the old layout.