Date: Wed, 13 Apr 2016 19:58:54 -0700 From: Ngie Cooper <yaneurabeya@gmail.com> To: "O'Connor, Daniel" <darius@dons.net.au> Cc: FreeBSD Hackers <freebsd-hackers@freebsd.org> Subject: Re: Improving commit logs Message-ID: <CAGHfRMAwZ-A7BspzCqAEniyQOcy1fmL85V4wjzG0gDBq6gbjtw@mail.gmail.com> In-Reply-To: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au> References: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Apr 12, 2016 at 5:18 PM, O'Connor, Daniel <darius@dons.net.au> wrote: > Hi everyone, > Some people on IRC were commenting about how commit logs without a 'why' in them are much less useful (both to others and yourself in the future) and how this can be improved in the FreeBSD project. > > Ed Maste pointed out that there is no real guidance about content of the commit log in the docs (https://www.freebsd.org/doc/en/articles/committers-guide/commit-log-message.html) except for the mechanical (PR, Reviewed By, etc). > > I propose changing the top part of it to.. > > ===== SNIP ===== > This section contains some suggestions and traditions for how commit logs are formatted and what they should contain. > > A commit log should explain *why* a commit has taken place, and to a lesser degree *how* and *what* was changed. > > The why of a commit message is absolutely critical to allow other people (including your future self) to understand > the reason a change was made. > > The how and what can be skipped if they are obvious (it's left as an exercise to the reader to determine what obvious is). > Generally speaking *what* is obvious due to the diff itself, the *how* can provide context and is more likely to be useful. > > Due to the use of git and use of svn blame it is highly desirable to have a 1 line summary of the commit, however don't let that constrain you, a summary plus more detailed explanation is fine if necessary. > > As well as including an informative message with each commit you may need to include some additional information. > ===== SNIP ===== > > Does anyone have any (constructive) comments or feedback? Isn't this just an extension of what others have written up before? Googling "writing good commit messages yielded: 1. http://chris.beams.io/posts/git-commit/ 2. https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message This is what I generally try to follow with commits... Thanks! -Ngie
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAGHfRMAwZ-A7BspzCqAEniyQOcy1fmL85V4wjzG0gDBq6gbjtw>