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
[-- Attachment #1 --] > On Feb 4, 2017, at 18:16, Steven Hartland <steven.hartland@multiplay.co.uk> wrote: > > 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? > > 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. > > Also I believe this is area the project as a whole can improve on, so I don't mean to single out anyone here. > > Anyway I hope people find this useful: > > 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. > > #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? > > 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. > > 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’t describe the rationale for the commit — especially when I need to assess the risk (backport needed, testing required, etc). Thanks! -Ngie [-- Attachment #2 --] -----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-----
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?978681FD-1FB2-4E5A-BBBF-43F3176DFE2B>