Re: [PATCH v4 2/2] post-receive-email: deprecate script in favor of git-multimail

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

On 07/15/2013 08:02 AM, Jonathan Nieder wrote:
> Michael Haggerty wrote:
> 
>> Add a notice to the top of post-receive-email explaining that the
>> script is no longer under active development and pointing the user to
>> git-multimail.
> 
> I think the spirit of this patch is sane.  Some thoughts on wording:
> 
> [...]
>> --- a/contrib/hooks/post-receive-email
>> +++ b/contrib/hooks/post-receive-email
>> @@ -2,10 +2,19 @@
>>  #
>>  # Copyright (c) 2007 Andy Parkins
>>  #
>> -# An example hook script to mail out commit update information.  This hook
>> -# sends emails listing new revisions to the repository introduced by the
>> -# change being reported.  The rule is that (for branch updates) each commit
>> -# will appear on one email and one email only.
>> +# An example hook script to mail out commit update information.
>> +#
>> +# ***NOTICE***: This script is no longer under active development.  It
>> +# has been superseded by git-multimail, which is more capable and
>> +# configurable and is largely backwards-compatible with this script;
>> +# please see "contrib/hooks/multimail/".  For instructions on how to
>> +# migrate from post-receive-email to git-multimail, please see
>> +# "README.migrate-from-post-receive-email" in that directory.
> 
> I think I'd say something like
> 
> (1)
> 	# An example hook script to mail out commit update information.
> 	#
> 	# This script is kept for compatibility, but it is no longer actively
> 	# maintained.  Consider switching to git-multimail, which is more
> 	# configurable and largely compatible with this script.  See
> 	# contrib/hooks/multimail/README.migrate-from-post-receive.
> 	#
> 	# This hook sends emails listing new revisions ...
> 
> or, if I wanted to emphasize the warning,
> 
> (2)
> 	# An example hook ...
> 	#
> 	# Warning: this script is kept for compatibility, but it is no longer
> 	# actively maintained.  Consider switching to ...
> 
> or, if I wanted to avoid seeming to promise that the script will be
> around in the future,
> 
> (3)
> 	# An example hook ...
> 	#
> 	# Warning: this script is no longer actively maintained.  Consider
> 	# switching to ...
> 
> I prefer (2), which makes it clear to the reader that it is dangerous
> to keep using the script (since no one is actively chasing down bugs)
> while also making it clear why a potentially buggy script with a good
> natural successor is still in contrib for now.  What do you think?

Honestly, as the main author of git-multimail, I am biased and think it
would be better for other people to make the decision about if/how/when
to annotate post-receive-email.  Any of your suggestions are fine with me.

Michael

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