Yes, I strongly endorse long form commit messages, though I’m often remiss about them myself. Until IDEs auto cross-reference JIRA, and we start sanitising our JIRA summaries, a commit record is going to be a better description of what has been done and why.
I think Jon is another proponent, who is more consistent about practicing what he preaches. It would be great to formalise this as an expectation, as if we’re honest the cost is not high to write a paragraph or two distilling the work that was done. > On 16 Aug 2022, at 17:36, Josh McKenzie <jmcken...@apache.org> wrote: > > >> >> something more descriptive like "Describe what the pull request fixes, why >> it is needed, and what branch(s) you expect it to be applied to." > I recall us having a conversation a long while ago about our commit messages > and whether they're optimal in their current format (defer all context to > JIRA) or whether there's value in adding a longer form digest of context in a > paragraph below the commit. > > Over time I've become more sympathetic to the approach of informative > long-form bodies (I think you advocated for this in the past Benedict?) - > google does a decent job of documenting the process and reasoning here: > https://google.github.io/eng-practices/review/developer/cl-descriptions.html > > One of the benefits of including information about the context of what you're > doing in the commit message, even if it's redundant with the JIRA ticket, is > that someone in-IDE using integrated annotation/blame can get the "why" of a > code-change in their existing workflow without having to jump out to a JIRA > ticket where the signal/noise ratio is often much poorer. This efficiency or > inefficiency is magnified the more historical patches you need to understand > to understand the context of the change you're making. > > Changing our commit message process to include this would also translate into > having that information available in PR's, and in the PR description body, > which we could easily lift over to the commit itself and/or JIRA ticket. >
