OSDir


[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Check those commit messages please!


Maybe I'm more pedantic than most, but I believe that a clean, clear
consistent commit log is an indication of a high-quality project. It's
also a great tool for users and maintainers alike.

The commit log becomes the release notes, which is the main way that
people find out what features are in our project.

* The first line of the commit message must be a concise and useful
description of the change.
* Prefix with JIRA case in brackets, if the change is not trivial. (If
you're wondering whether it is trivial, ask yourself whether anyone
might ever request this change to be back-ported to a maintenance
branch.) Create a JIRA case if necessary.
* The message is often, but not always, the same as the JIRA subject.
If the JIRA subject is not clear, change it (perhaps move the original
subject to the description of the JIRA case, if it clarifies).
* Start with a capital letter.
* Do not finish with a period.
* Use imperative mood ("Add a handler ...") rather than past tense
("Added a handler ...") or present tense ("Adds a handler ...").
* If possible, describe the user-visible behavior that you changed
("FooCommand now creates directory if it does not exist"), rather than
the implementation ("Add handler for FileNotFound").
* If you are fixing what is clearly a bug, it is sufficient to
describe the bug ("NullPointerException if user is unknown") and
people will correctly surmise that the purpose of your change is to
fix the bug.
* If the contributor is not a committer, add their name in parentheses
at the end of the message.
* Read the messages of previous commits, and follow their style.

Julian



On Thu, May 31, 2018 at 5:55 PM, Josh Elser <josh.elser@xxxxxxxxx> wrote:
> I'm noticing some recent commits on Avatica where we have no lineage on what
> JIRA issue the change was for. Please make sure you have the
> "[CALCITE-XXXX]" included in the commit message when we're not dealing with
> something trivial.
>
> No need to ACK this, take responsibility, or anything of the such. We've all
> done it in the past, just wanted to drop a reminder :)
>
> Thanks!