On Tue, 15 Jun 2021 at 01:12, Martin Sebor wrote: > > On 6/14/21 10:25 AM, Jonathan Wakely via Gcc-patches wrote: > > I think this is an improvement on the current structure of the docs, > > but I'd like to hear what others think. > > The text looks more detailed and arguably more accurate but also > makes it sound more complicated and rigid than necessary. It > also doesn't look like the commit hook tries to enforce many of > these elements. If it did, quite a number of commits would fail. > > So I'm not sure about the value of documenting expectations that > only few commits would meet.
We don't have to be too strict, but encouraging good practice still makes the commit logs more useful. Even if only 50% of commit follow it, that still seems to make the logs easier to skim than if there is no consistency at all. > E.g., including the Component tag, > or putting PRnnnnn at the end of the Subject line with no space > (why ask for no space and not, for example PR #nnnnn?) In fact, That was always there, I just moved it from one page to another. I have traditionally used a space before the bug number, so I'm fine with that format, but I don't really think it makes the docs better to list too many variations. And I am not trying to make big changes to the policy with this patch, just reorganize the existing docs to reflect the modern workflow (i.e. Git commits with automatically generated ChangeLog files, rather than everything being about the ChangeLog). > unless we mean it (and are willing to enforce it) I think it > would be best to either leave it out completely, or make it clear > that it's not required. If we don't enforce it, then it's not required. Commits that don't do it will still get in. I think suggesting a single format (but allowing variations on it) is **much** better than not saying anything at all. For new contributors it's helpful to say "this is what we want" so they have a guideline to follow. My revised patch sent a few minutes ago adds: <p>A major benefit of a good, descriptive subject line is that it makes the output of <code>git log --oneline</code> more useful. Including the component tag and bug number(s) helps with that, but isn't compulsory if the subject is already clear and has enough context.</p> Does that make you happier?
