Re: [RFC] Add a new email notification script to "contrib"

[Michael Haggerty <mhagger@alum.mit.edu>]

On 07/16/2012 05:57 PM, Marc Branchaud wrote:
> On 12-07-14 02:59 AM, mhagger@alum.mit.edu wrote:
>> * Various changes to the format of the notification emails:
>>
>>    * List commits in chronological (rather than topological) order.
>
> I'm not sure this is a good idea.  Topological order ensures that the commits
> apply in the order they're presented.  If you're attached to chronological
> ordering, perhaps make this configurable?

I should have been more accurate.  The output is not, strictly speaking, 
in chronological order; rather, it is in "--reverse" topological order 
(which is approximately chronological).  Perhaps this should be called 
"causal" order :-)

The old script listed the commits in default "git log" order, which I 
believe is called topological order, and is approximately 
reverse-chronological.

>> This script does not support the "hooks.showrev" configuration option.
>
> This is pretty much the only downside.  We use hooks.showrev to insert a link
> to our gitweb for each commit.

I thought of hooks.showrev as mostly a poor-man's way of generating 
commit diffs, and that is why I didn't add support for it.  But your use 
case is indeed interesting.

Maybe you could be more specific about what kinds of places in the 
emails you would like to add links, and how you like the links to look, 
to give me the idea of what you want.  I'm sure we can find a way to add 
it to the script.

> I'd be OK with dropping support for hooks.showrev if there was some other way
> to add extra info to the commit email.  Perhaps another template string after
> REVISION_HEADER_TEMPLATE, one that's empty by default?

ISTM that you could already just append your special content to 
REVISION_HEADER_TEMPLATE rather then having to add a new template:

     import sys, post_receive_multimail
     post_receive_multimail.REVISION_HEADER_TEMPLATE += """..."""
     post_receive_multimail.main(sys.argv[1:])

And I plan to make the template strings even easier to customize (see 
below).

>> [3] When announcing a new annotated tag, post-receive-mail lists *all*
>>      of the commits since the previous annotated tag.  I found such
>>      emails rather confusing than useful, so I omitted this feature.
>
> I actually like that aspect of the current script.  Another configuration
> flag, maybe?

Yes, I don't think it would be so hard to retrofit this behavior into 
the script.  Actually, I think I would teach it how to generate *two* 
emails for annotated tags:

* one in the new script's current minimalist style, sent to the
   "hooks.refchangelist" email addresses

* a second in the longer style of the old script, sent to the
   "hooks.announcelist" email addresses (only if configured)

People could add themselves to one mailing list or the other, depending 
on what they prefer.  Other suggestions are welcome.

> As a replacement for the current script, I think this is great.  One thing
> that I think would help make it more maintainable is to have it read template
> strings from a file, so that people can customize templates without changing
> the script itself.  It would also help to document all the allowed template
> variables.  You might also consider expanding the templates to cover all
> strings that might appear in the emails, as that would basically
> internationalize the code and let people create translations.
>
> Similarly, it would be good for folks who write their own Environments to
> also be able to use a separate file instead of modifying the script itself.

We seem to be on the same wavelength; these are all things that I have 
planned under the rubric of "improved configurability".  My tentative 
plan is to support two modes of use:

1. Use the script directly as a post-receive hook, to be executed 
directly as a program, configurable only via configuration settings

2. Write a short post-receive hook that imports 
post-receive-multimail.py as a Python module.  The calling script would 
be able to affect the script's behavior at a deeper level by, for 
example, defining a new Environment class or changing the template 
strings, then it would call a function in the module to do the real 
work.  See above for a trivial example.

> Thanks again -- this is good work!

Thanks for the feedback.  If you want to get involved, please let me 
know...having more than one contributor would undoubtedly help the 
script's chances of being accepted into the git project.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/