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

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Jul 15, 2013, 06:02 UTC
Message-ID: <20130715060245.GD2962@elie.Belkin>
In-Reply-To: <1373789343-3189-3-git-send-email-mhagger@alum.mit.edu>

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:

[...]

Show 18 quoted lines

> --- 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?

Thanks, Jonathan