Date: Sat, 4 Feb 2017 18:46:25 -0800 From: "Ngie Cooper (yaneurabeya)" <yaneurabeya@gmail.com> To: Steven Hartland <steven.hartland@multiplay.co.uk> Cc: Mateusz Guzik <mjg@FreeBSD.org>, src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r313260 - head/sys/kern Message-ID: <978681FD-1FB2-4E5A-BBBF-43F3176DFE2B@gmail.com> In-Reply-To: <42c790bb-df12-2a50-6181-24bac5c72d34@multiplay.co.uk> References: <201702050140.v151eRXX090326@repo.freebsd.org> <42c790bb-df12-2a50-6181-24bac5c72d34@multiplay.co.uk>
next in thread | previous in thread | raw e-mail | index | archive | help
--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 = <steven.hartland@multiplay.co.uk> 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--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?978681FD-1FB2-4E5A-BBBF-43F3176DFE2B>