On 04.12.2017 23:01, Julian Foad wrote: > Johan Corveleyn wrote: >> [...] >> Hm, yes, I agree with the "don't write the same thing twice". But >> perhaps the "general description" above the list of affected files >> would be a better place: > [...] >> Though, indeed, we're not required to always have a "general >> description", and can just start with the affected files, if the >> change is simple. So ... not sure. >> >> That's the thing I'm most uncertain of at the moment: how to fit this >> scheme precisely into our current log message style, without >> interfering too much, keeping them as readable as possible for human >> readers. >> >> Maybe a syntax with '@' would be better, like annotations in Java or >> doxygen. Like: > [...] >> or as a suffix: > [...] >> Just thinking out loud here ... > [...]> Hmmmm > > Now you're over-thinking it. What you said first, what you use at > work, is fine. Run with it!
IMO the important thing is to make the tagging in the log messages as human-friendly as possible. That's what made the contribulyzer work so well: there were no $[@foo;\\} syntactical quirks to remember and the syntax is permissive. Therefore I think stsp's suggestion of just taking the summary line in the log message as the CHANGES entry is more likely to produce useful results than any magic tagging. I don't think it's all that important to classify the change into user-facing, etc., at commit time. All we need, IMO, is a way to signal whether the change is or is not important. So I'd suggest we use stsp's proposal with a small difference: by default, every log message that has a summary line is important. If it's not, start the first line with a # to tell the script to ignore it. That way, it takes extra thought and effort to exclude a commit from the CHANGES summary, which is IMO preferable to having to put in extra thought and effort to have it included. It's easier to prune unnecessary entries from the summary than it is to dig into commit history to find the missing ones. -- Brane
