From owner-svn-src-head@freebsd.org Sun Feb 5 02:46:23 2017 Return-Path: Delivered-To: svn-src-head@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 4D2EFCD19B1; Sun, 5 Feb 2017 02:46:23 +0000 (UTC) (envelope-from yaneurabeya@gmail.com) Received: from mail-pf0-x242.google.com (mail-pf0-x242.google.com [IPv6:2607:f8b0:400e:c00::242]) (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 199BE1277; Sun, 5 Feb 2017 02:46:23 +0000 (UTC) (envelope-from yaneurabeya@gmail.com) Received: by mail-pf0-x242.google.com with SMTP id e4so4313112pfg.0; Sat, 04 Feb 2017 18:46:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=subject:mime-version:from:in-reply-to:date:cc:message-id:references :to; bh=qstsLE0OEOSucKRdZ/HKDVZ3nrDAbZtPaiKhPCOIpqs=; b=ZevhOQiQNtQviPhNlRnjfBsl4XfAGBL5fmoJeLwbRjngdx8+rUjbd5daXA+aAw/03E MIEXwtlUuBk7M73Z3FYC2KUXVz6xVtqzQNZN8aJ/OTIiZcxzz0xtwMLklUzJohXQv1To 2vyt+moJ8zIpt92cPZJkbXgcFzsK73vSaCBGjqYhnkZoSuy7uquY+M6jbF4zuLjLClmY /TL18nu07s9XMAg0gtCDqWVHtAlKV4d6lsXM1woW+Kdo4nyZwFxzkoUJSwcvnpzsBQUx T3dUyzcXt1oIKBDrkaX96vrHRwppiFh7lvJfgscg3tj6naR5nVS0bDuGlGjovAeHXjix fQug== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:mime-version:from:in-reply-to:date:cc :message-id:references:to; bh=qstsLE0OEOSucKRdZ/HKDVZ3nrDAbZtPaiKhPCOIpqs=; b=MJuX7wb5CKW/daH9X3hvrUKUqwaRu/7rL5CmDktuIJSIa7tMSDxdlblzsfF6iXofQr CEMm9vPYO/ymO9KSkfhkPycgtr9kapAPMGzxs/bbSD9WA037qUMuMWw0slI5JNu/jFPa JFbQbNAkmHVPJr+J64VPzMq15WIFpaoS61EULFmYFjiKQzPIzIrA+RTtRpNMPBzPzxbG W4B5IacxHC4Fkk79Kw92o46dA324Kur0Plqna9Zweoz4QFQyAoJU9hk9JpbvorLUMzOf fCyCao4KcVo2z3m3iFIv18FLyutG8KtOFFS4mcDRpl1ZNOMvV/+rlPoAlR6l37pqjsYp kQJg== X-Gm-Message-State: AIkVDXIpFJeuV3rImPuKtuN8vqxTjeGzGKxZC4/9eQbdlFS0adzVpIRIeXs8Tk8P5BBq6A== X-Received: by 10.99.66.193 with SMTP id p184mr5804137pga.213.1486262782651; Sat, 04 Feb 2017 18:46:22 -0800 (PST) Received: from pinklady.local (c-73-19-52-228.hsd1.wa.comcast.net. [73.19.52.228]) by smtp.gmail.com with ESMTPSA id y6sm78736533pgc.1.2017.02.04.18.46.21 (version=TLS1 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sat, 04 Feb 2017 18:46:22 -0800 (PST) Subject: Re: svn commit: r313260 - head/sys/kern Mime-Version: 1.0 (Mac OS X Mail 9.3 \(3124\)) Content-Type: multipart/signed; boundary="Apple-Mail=_1CF7A619-F4AE-498A-8F1A-07565308AB52"; protocol="application/pgp-signature"; micalg=pgp-sha512 X-Pgp-Agent: GPGMail From: "Ngie Cooper (yaneurabeya)" In-Reply-To: <42c790bb-df12-2a50-6181-24bac5c72d34@multiplay.co.uk> Date: Sat, 4 Feb 2017 18:46:25 -0800 Cc: Mateusz Guzik , src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Message-Id: <978681FD-1FB2-4E5A-BBBF-43F3176DFE2B@gmail.com> References: <201702050140.v151eRXX090326@repo.freebsd.org> <42c790bb-df12-2a50-6181-24bac5c72d34@multiplay.co.uk> To: Steven Hartland X-Mailer: Apple Mail (2.3124) X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 05 Feb 2017 02:46:23 -0000 --Apple-Mail=_1CF7A619-F4AE-498A-8F1A-07565308AB52 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 > On Feb 4, 2017, at 18:16, Steven Hartland = wrote: >=20 > Hi Mateusz could you improve on the commit message as it currently = describes what is changed, which can be obtained from the diff, but not = why? >=20 > I hope on one feels like I'm trying to teach them to suck eggs, as I = know everyone here has a wealth of experience, but I strongly believe = commit messages are a very important way of improving the overall = quality of the code base by sharing with others the reason for changes, = which they can then learn from. I know I for one love picking up new = nuggets of knowledge from others in this way. >=20 > Also I believe this is area the project as a whole can improve on, so = I don't mean to single out anyone here. >=20 > Anyway I hope people find this useful: >=20 > When I write a commit message I try to stick to the following rules = which I believe helps to bring clarity for others about my actions. > 1. First line is a brief summary of the out come of the change e.g. > Fixed compiler warnings in nvmecontrol on 32bit platforms > 2. Follow up paragraphs expand on #1 if needed including details about = not just what but why the change was made e.g. > Use ssize_t instead of uint32_t to prevent warnings about a comparison = with different signs. Due to the promotion rules, this would only = happen on 32-bit platforms. > 3. When writing #2 include details that would not be obvious to = non-experts in the particular area. >=20 > #2 and #3 are really important to sharing knowledge that others may = not know, its quite relevant to this commit msg, as while it may be = obvious to you and others familiar with the atomic ops, to the rest of = us we're just wondering why make this change? >=20 > N.B. The example is based on Warner's recent commit purely as an = example, which had a good why, just missing the brief summary. >=20 > While on this subject are there any official guidelines to writing = commit messages, if no should we create some? Please. It really irritates me when I find similar commit = messages at $work from people that don=E2=80=99t describe the rationale = for the commit =E2=80=94 especially when I need to assess the risk = (backport needed, testing required, etc). Thanks! -Ngie --Apple-Mail=_1CF7A619-F4AE-498A-8F1A-07565308AB52 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=signature.asc Content-Type: application/pgp-signature; name=signature.asc Content-Description: Message signed with OpenPGP using GPGMail -----BEGIN PGP SIGNATURE----- Comment: GPGTools - https://gpgtools.org iQIcBAEBCgAGBQJYlpIBAAoJEPWDqSZpMIYV3HgP/3K80/KkQz9/Rhs4RdAbuYFb sFlOA1dE1enj07CkpG5cgz1iJYiBxZC09pL5cC1BLyzrJrcDNT9h4OEQY2hjg0NH 7mJdeBFpvnbP1qQazuhM3jO/Ww/GdVXmGlGpaTR17WzljVzIpjoe1B//f1HhQkLu GKVOgXolxvYYD8tMfUoGMXTJbd1KLwAKZLPAc4d59wBRrPpwDw5btAtIfZC9lJJ0 dH54RrjRFDfcTmAPTrdUuUNaqO6QCFPwlcKFWeO8MlFJicovAPqhTJJfUTJ1+4hF X8gQE9o65DZBd/RiY/y80MVHtqUIzbjzNwhEafRHsJXMPuY5LOV9roXHiGm/VMQw Wt57ROiDZqXoY02djIlOKQe3Ux5TqlB5kVfTGU6UXQ7kqUXYI19S76nEiU4aONS4 74KKiklzvVaAJlcF8RmI0RRQp3Cyqy1VIl+J09i/I7HycW+7ry6kcsSfMcIdGNKy Z6iRu+RkIZAOaHHNNQ3egQW0wgo2WUoPODg98eE+0XGRSWVr4KsbqvGm6O1KBPEl o/vFE7lqbchXeykNm1iZNZwJYwZB1ioXDxWE0Aw3oQ5bpFnbiF6yj52PjatLLzwl xHGkMRyUpy4W0O6XLYR+RZAXg1K/rzZvAmblAG7dLItz7EXGdZOK08spb5ESRv6K 1VWAyPOv3SoG2b1EHiM7 =6wLj -----END PGP SIGNATURE----- --Apple-Mail=_1CF7A619-F4AE-498A-8F1A-07565308AB52--