Hi Accumulo Devs! Every once in a while, I share this link with people (I think I have shared it on this list before as well), with helpful tips on writing good git commit log messages. I'm sharing it again today because we have had new contributors in the last year, some may find this useful:
https://chris.beams.io/posts/git-commit/ There's a few key points in this: 1. Separate subject from body with a blank line 2. Limit the subject line to 50 characters 3. Capitalize the subject line 4. Do not end the subject line with a period 5. Use the imperative mood in the subject line 6. Wrap the body at 72 characters 7. Use the body to explain what and why vs. how There's a complete example in the link for reference. ***** In addition, I've made some observations of my own regarding Accumulo practices that I think we should strive to improve upon (many of which I'm guilty of): * We should avoid "Closes #N" or "Fixes #N" or "Close #N" or "Fix #N" or other closing keywords in the subject line of the commit. This saves valuable space that could be used to summarize the change in the subject line. Instead, place those in the body of the message somewhere. The example in the article is to place them at the end of the body, but I think they can often be helpful inline inside the body instead. * Use "Fix" in the subject line, not "Fixes" (see imperative mood recommendation above). * GitHub has a convention of appending PR number at the end of the subject when you merge from the web interface, in parenthesis, as in: `Fix the Test (#NNNN)`. This is a nice convention. If you have to merge a PR manually from the CLI (like to resolve merge conflicts or to cherry-pick to another branch), it's good to adopt the same convention if you're closing a PR. * Use markdown syntax in the body where appropriate, including bullet points, paragraphs, and backticks for code (especially use backticks if you reference something with an `@` in it, to avoid tagging a user by that name on GitHub. Like, `@Test` or `@Deprecated`) * Use the "Squash and merge" option in GitHub's interface under most circumstances. This keeps the git history nice and clear. If we need to reference individual changes that occurred on a PR during the review process, we can go back to the PR itself to look at those, but this is almost never necessary. Sometimes, "Create a merge commit" is needed, to preserve separate commits for independent changes that happened in the same PR, but these are rare. (Two examples I can think of is if we update the formatter config or thrift config, and then want to have a separate commit for the resulting formatting/generated code changes, but want to put them in a single PR.) * When using GitHub to merge (and really, even when using the CLI), always review the commit log messages and make any final changes before submitting. This is your last chance to edit and/or polish, and it's an opportunity to remove intermediate messages from the log like "fix typo" or "fix test" or "address code review comments" that don't add value to the overall message, and to include changes you may have forgotten, like co-author acknowledgements or correct any deviation from when the commit messages were first authored and the final result. When you merge, the commit message should reflect what the change actually does in its final form, after all code reviews and updates to the PR, not your first draft and the steps it took you to get there. Anyway, I hope these tips help somebody. Thanks, Christopher
