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@xxxxxxxxxxxx http://softwareswirl.blogspot.com/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html