On Fri, 11 Jun 2021 at 10:08, Jonathan Wakely wrote: > > On Thu, 10 Jun 2021 at 18:06, Martin Sebor <mse...@gmail.com> wrote: > > By "the subject line" are you referring to what the ChangeLog calls > > $git_description, and, AFAICS, consists of multiple lines? (Based > > on the Example patch on the conventions page. In that example, > > the PR87763 reference is in the middle of line 3.) > > > No, I mean the first line of the $git_description, which would also be
Sorry, the end of that sentence got lost on my clipboard. The first line of the $git_description would also be the Subject of your email, if you follow established Git best practices (e.g. in the kernel, GitHub and elsewhere). For further reading: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_commit_template https://chris.beams.io/posts/git-commit/ https://reflectoring.io/meaningful-commit-messages/#formatting This one suggests a lot more structure, which is partially in conflict with GCC's own guidelines, but it agrees that the commit msg should start with a single-line description: https://www.conventionalcommits.org/en/v1.0.0/ If you're not already doing a brief "subject" line in your git commits, you're Doing It Wrong! This is why I want the docs to go into more detail on the content of the $git_description part of the git commit msg, because then reusing that subject as your email Subject: is a no-brainer. So if you're confused whether I mean the (first line of the) $git_description or the email Subject: you should ask yourself why you think there is any distinction between the two :-) And for the avoidance of doubt ... > > Again, I'm not sure what exactly you mean by "the changelog" here. > > Are you referring to the whole commit message or just to what > > the conventions refer to as the ChangeLog entry? > > The latter. When I say changelog, I mean the changelog, and when I say commit message, I mean the whole git commit message. I don't say "changelog" to mean the whole git commit message. I'm using the terminology of the codingconventions.html page: "ChangeLog entries are part of git commit messages and are automatically put into a corresponding ChangeLog file." Using "changelog" to mean the whole commit message would be confusing and/or ambiguous.
