Ralph,

The one thing that I'd like to make sure is kept in the "summary"
part of the first paragraph is the Bug #, if any. This makes it
easy to cross reference back to the more informative discussion
in the bug tracker.

Otherwise, fine with me (in case you care).

Regards,
Ray
__________________________________________________________________
Ralph Giles wrote:
> This message is primarily for those with commit access to Ghostscript...
>
> We're relaxing the 'form' of the commit message. Please don't use the
> 'Details' heading any more. Instead try to summarize the 'what' of the
> change in the first paragraph. It's ok the be brief, even fit it on
> one line. Then describe the motivation, any further details, and
> analysis after that. Both parts are important in a good commit
> message.
>
> Likewise, it's fine not to include an 'Expected Differences' section.
> If you do expect specific progressions or regression, just summarize
> them briefly; the per-commit regression reports already document what
> has changed. If you need to include a long list anyway, put it at the
> end, separated by the header, as before.
>
> Details:
>
> For the past several years we've divided our commit messages in
> multiple sections: a short summary of the change, a section with
> detailed analysis not of casual interest, and a list of expecting
> rendering differences. The three sections were divided by specific
> headers which were used to strip the details from the generated
> 'Changes.htm' and 'History*.htm' documentation files which reproduced
> the content of the repository commit messages in release packages.
>
> Henry has complained that the headings peeve him, and I think the
> technical change log documentation is redundant when there is easy web
> access to the repository itself. Certainly there are still people
> referring to the documentation for this, but he asked me to decide and
> I have done so. I will still create a Changes file for the February
> release, but mark it as deprecated and point people at repository for
> future reference. If there's convincing argument, we can reconsider in
> August.
>
> So, no more "Details" header. Note that it's best practice in the
> newer distributed version control systems to summarize the commit
> message by the first line or sentence, which is the origin of the
> recommendation to brevity above. I think this is quite useful. It can
> be hard to get the essential summary down to one line, but I'm getting
> better at it. In any case, our new 'first paragraph' convention is
> intended to give us some future proofing should we need filtering
> again in the future, while the looser style will read better and be
> more flexible.
>
> The '"Expected Differences" heading was also used for automated
> stripping, but we added the section in the first place so it could be
> used to update the nightly regression runs for progressions. Now that
> we test every commit, I don't think that's so important any more, and
> plans to automate the updates were never implemented. We expect
> developers to do reasonable testing, and investigate any unexpected
> regression results; I think that's good enough.
>
>  -r
>

_______________________________________________
gs-devel mailing list
gs-devel@ghos...
http://ghostscript.com/cgi-bin/mailman/listinfo/gs-devel