From owner-freebsd-hackers@freebsd.org Thu Apr 14 02:58:56 2016 Return-Path: Delivered-To: freebsd-hackers@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id D6FDCB0F67E for ; Thu, 14 Apr 2016 02:58:56 +0000 (UTC) (envelope-from yaneurabeya@gmail.com) Received: from mail-lf0-x230.google.com (mail-lf0-x230.google.com [IPv6:2a00:1450:4010:c07::230]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority G2" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 5B0181939 for ; Thu, 14 Apr 2016 02:58:56 +0000 (UTC) (envelope-from yaneurabeya@gmail.com) Received: by mail-lf0-x230.google.com with SMTP id j11so93209786lfb.1 for ; Wed, 13 Apr 2016 19:58:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc; bh=sqD9TdZyx1RxdOTM6nsfSy1TBx3lv7OiqwRXKP8Td8o=; b=adO908ilIQUhR0dcOHNGm6fLfR/Riw7Am8TBG0Pe3yPitLVLFjjMT2JW9bcb5/Wb0D YBKUVd0CW5ldkTsI5b5ifI+amen1YxtggJUL4Ko9T1yHluCDCNhT7w8KqXscH8LfyNBb YGtdNQwo+1YAqUM8Z7xIu0kC2ZxbEyp5zFUb9zHIfWyykAUWWlAhuMZyOaDw/sPX9UBF ybW0rtBVC2yErD7qdZMjZTOqpdxirdUO3g9numjy0SUonCiuIbx2lhVS50XYCdh0cHho Kovol7CwBuBFweFbRcllzwq8hiNy/Fo7cp68HPDGjByVTw0UBvRdCgiGVqxyKWgYciXp U80A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:in-reply-to:references:date :message-id:subject:from:to:cc; bh=sqD9TdZyx1RxdOTM6nsfSy1TBx3lv7OiqwRXKP8Td8o=; b=PMOhYYdSDpc76M21s2o6fSyhJcr82+QsOF1EAN+rBua4L81e1sZpb+paCNRMeJlhkZ PU4UKMSv2GdHgHZaxxJESa3oHr9ThUCQVdMTFyGlAzRUpcCSLFzu7opjDl/c8wL6Zu2v vpinifbb50hYNn5+36a7HebWuC9OkOKjOW/lHviWEIeYrNbHwYcaBGm67idRXWjdMVw5 dBwCZyAvPWl1oHNPGU8WfagRpTbNYH5yRD0cGa+PiIyZEfZuIjL5RoQMYUjgRpMwyQAF et4OGKvgtPeOkiruyvZFE+nNghvZK1oNv1KoqJlikaGFYxZJicmmfk6YqIwH4KXi8paQ wJIA== X-Gm-Message-State: AOPr4FXUpG6iGrhYFfz/GNBakDJKqDF2janwqlyEaTCX3PSkZIWLLWvFNOpOGMA3Q867mHVupWxKM3BXDDQPzg== MIME-Version: 1.0 X-Received: by 10.112.52.196 with SMTP id v4mr4780595lbo.59.1460602734205; Wed, 13 Apr 2016 19:58:54 -0700 (PDT) Received: by 10.112.236.33 with HTTP; Wed, 13 Apr 2016 19:58:54 -0700 (PDT) In-Reply-To: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au> References: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au> Date: Wed, 13 Apr 2016 19:58:54 -0700 Message-ID: Subject: Re: Improving commit logs From: Ngie Cooper To: "O'Connor, Daniel" Cc: FreeBSD Hackers Content-Type: text/plain; charset=UTF-8 X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 14 Apr 2016 02:58:56 -0000 On Tue, Apr 12, 2016 at 5:18 PM, O'Connor, Daniel 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