Annotation of htdocs/developers/commit-guidelines.html, revision 1.72
1.50 jym 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
1.31 kano 2: <html>
1.1 jschauma 3: <head>
4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
1.27 heinz 5: <meta name="generator" content="Website XSL Stylesheet V2.6.0">
1.21 jschauma 6: <link rel="home" href="../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
7: <link rel="up" href="../developers/." title="NetBSD Developer Documentation">
1.27 heinz 8: <link rel="previous" href="../developers/announce.html" title="NetBSD Developer Documentation: News story guidelines">
1.30 wiz 9: <link rel="next" href="../developers/cvs-repos/." title="CVS Repository Issues">
1.27 heinz 10: <link rel="first" href="../developers/announce.html" title="NetBSD Developer Documentation: News story guidelines">
11: <link rel="last" href="../developers/www.html" title="NetBSD Developer Documentation: Information about the www
12: mailing list">
1.41 dsieger 13: <link rel="stylesheet" href="../global.css" type="text/css">
1.1 jschauma 14: <title>NetBSD Commit Guidelines</title>
15: </head>
1.27 heinz 16: <body class="website"><div class="webpage">
1.34 dsieger 17: <a name="developers-commit-guidelines"></a><div id="top"><a href="#mainContent" class="doNotDisplay doNotPrint">Skip to main content.</a></div>
1.62 maya 18: <div id="centralHeader"><div id="logo">
1.54 jym 19: <a href="../"><img alt="[NetBSD Logo]" src="../images/NetBSD-smaller.png"></a><div id="name"><a href="../">
1.52 jym 20: The NetBSD Project
1.54 jym 21: </a></div>
22: <div id="slogan"><a href="../">
1.52 jym 23: “Of course it runs NetBSD”
1.54 jym 24: </a></div>
1.62 maya 25: </div></div>
1.63 maya 26: <input id="hamburger" type="checkbox"><label class="menuicon" for="hamburger"><span></span></label><div id="navBar" role="navigation">
1.37 dsieger 27: <span class="doNotDisplay">
28: Navigation:
1.50 jym 29: </span><ul>
30: <li><a href="../">
31: Home</a></li>
32: <li>
33: <a href="../">
1.53 wiz 34: News & Media</a><ul>
1.50 jym 35: <li><a href="../changes/">
36: Recent changes</a></li>
1.65 maya 37: <li><a href="//blog.NetBSD.org/">
1.50 jym 38: NetBSD blog</a></li>
39: <li><a href="../gallery/events.html">
40: Events</a></li>
41: </ul>
42: </li>
43: <li>
44: <a href="../about/">
45: About</a><ul>
46: <li><a href="../about/">
47: NetBSD</a></li>
1.71 maya 48: <li><a href="../people/developers.html">
49: NetBSD developers</a></li>
1.50 jym 50: <li><a href="../gallery/">
51: Advocacy</a></li>
52: </ul>
53: </li>
54: <li>
55: <a href="../docs/">
56: Documentation</a><ul>
57: <li><a href="../docs/misc/index.html">
58: FAQ & HOWTOs</a></li>
59: <li><a href="../docs/guide/en/">
60: The Guide</a></li>
1.66 maya 61: <li><a href="http://man.NetBSD.org/">
1.50 jym 62: Manual pages</a></li>
1.65 maya 63: <li><a href="//wiki.NetBSD.org/">
1.50 jym 64: Wiki</a></li>
65: </ul>
66: </li>
67: <li>
68: <a href="../support/">
69: Support</a><ul>
70: <li><a href="../support/send-pr.html">
71: Problem report guide</a></li>
72: <li><a href="../cgi-bin/sendpr.cgi?gndb=netbsd">
73: Report a bug</a></li>
74: <li><a href="../support/query-pr.html">
75: Query bug database</a></li>
76: <li><a href="../support/security/">
77: Security</a></li>
78: </ul>
79: </li>
80: <li>
81: <a href="../community/">
82: Community</a><ul>
1.68 leot 83: <li><a href="//blog.NetBSD.org/">
84: Blog</a></li>
1.50 jym 85: <li><a href="../mailinglists/">
86: Mailing lists</a></li>
1.65 maya 87: <li><a href="//mail-index.NetBSD.org/">
1.50 jym 88: List archives</a></li>
89: </ul>
90: </li>
91: <li>
92: <a href="../developers/">
93: Developers</a><ul>
1.67 maya 94: <li><a href="http://cvsweb.NetBSD.org/">
1.50 jym 95: Browse source</a></li>
1.65 maya 96: <li><a href="//nxr.NetBSD.org/">
1.50 jym 97: Cross-reference</a></li>
1.65 maya 98: <li><a href="//releng.NetBSD.org/">
1.50 jym 99: Release engineering</a></li>
1.65 maya 100: <li><a href="//wiki.NetBSD.org/projects/">
1.50 jym 101: Projects list</a></li>
102: </ul>
103: </li>
104: <li>
105: <a href="../ports/">
106: Ports</a><ul>
107: <li><a href="../ports/history.html">
108: History</a></li>
109: <li><a href="../ports/emulators.html">
110: Emulators</a></li>
111: </ul>
112: </li>
113: <li>
1.65 maya 114: <a href="//www.pkgsrc.org/">
1.50 jym 115: Packages</a><ul>
1.66 maya 116: <li><a href="http://www.pkgsrc.se/">
1.50 jym 117: Browse packages</a></li>
1.65 maya 118: <li><a href="//releng.NetBSD.org/index-pkgsrc.html">
1.50 jym 119: Release engineering</a></li>
120: </ul>
121: </li>
122: </ul>
1.34 dsieger 123: </div>
124: <div id="content"><div class="fullWidth"><div class="rowOfBoxes">
125: <h1>NetBSD Commit Guidelines</h1>
1.55 tron 126: <div class="sect1">
1.12 wiz 127: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.1 jschauma 128: <a name="guidelines"></a>
129: The following Commit Guidelines define the Project's standards for making
130: commits to the source tree:
1.12 wiz 131: </h2></div></div></div>
1.1 jschauma 132:
133:
134:
1.48 spz 135: <div class="orderedlist"><ol class="orderedlist" type="1">
136: <li class="listitem">
1.55 tron 137: <div class="sect2">
1.12 wiz 138: <div class="titlepage"><div><div><h3 class="title">
139: <a name="know-thy-code"></a>Commit only code you are familiar with.</h3></div></div></div>
1.1 jschauma 140:
141: <p>
142: If you are not sure if the code you plan to commit is acceptable
143: (e. g. when taking code that was submitted with a problem report),
144: ask a developer who is familiar with that part of the system for
145: review. If you're new to the Project, check with your sponsor.
146: </p>
147: </div>
148: </li>
1.48 spz 149: <li class="listitem">
1.55 tron 150: <div class="sect2">
1.12 wiz 151: <div class="titlepage"><div><div><h3 class="title">
152: <a name="tainted"></a>Do not commit tainted code to the repository.</h3></div></div></div>
1.1 jschauma 153:
154: <p>
155: If you commit code that was not written by yourself, double check
156: that the license on that code permits import into the NetBSD source
157: repository, and permits free distribution. Check with the author(s)
158: of the code, make sure that they were the sole author of the code
159: and verify with them that they did not copy any other code.
160: </p>
161: </div>
162: </li>
1.48 spz 163: <li class="listitem">
1.55 tron 164: <div class="sect2">
1.12 wiz 165: <div class="titlepage"><div><div><h3 class="title">
1.29 jschauma 166: <a name="repository"></a>Do not commit code from foreign trees.</h3></div></div></div>
167:
168: <p>
169: Do not commit code from a tree checked out from anywhere but from
170: cvs.NetBSD.org. Note that all developers have access to the private
1.41 dsieger 171: <a class="ulink" href="restricted.html#rsync" target="_top">rsync-over-ssh service on
1.29 jschauma 172: cvs.NetBSD.org</a>.
173: </p>
174: </div>
175: </li>
1.48 spz 176: <li class="listitem">
1.55 tron 177: <div class="sect2">
1.29 jschauma 178: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 179: <a name="intrusive"></a>
180: The more intrusive your changes are the higher is the level of
181: required prior approval.
1.12 wiz 182: </h3></div></div></div>
1.1 jschauma 183:
1.55 tron 184: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.48 spz 185: <li class="listitem">
1.1 jschauma 186: <p>
187: "Obvious" fixes can be committed without any prior discussion
188: or review. (The definition of "obvious" in the GCC Project is:
189: "could not possibly cause anyone to object." We adopt this
190: definition here)
191: </p>
192: </li>
1.48 spz 193: <li class="listitem">
1.1 jschauma 194: <p>
195: All other (i. e. "non-obvious") fixes <span class="emphasis"><em>should</em></span>
196: have a review.
197: </p>
198: </li>
1.48 spz 199: <li class="listitem">
1.1 jschauma 200: <p>
201: Implementing (significant) new features requires a prior
202: discussion on an appropriate technical mailing list.
203: </p>
204: </li>
1.48 spz 205: <li class="listitem">
1.1 jschauma 206: <p>
1.46 pooka 207: Adding a completely new package (e.g. openldap) requires
208: prior discussion on a mailing list <span class="emphasis"><em>and</em></span>
209: approval from core.
1.1 jschauma 210: </p>
211: </li>
212: </ul></div>
213: </div>
214: </li>
1.48 spz 215: <li class="listitem">
1.55 tron 216: <div class="sect2">
1.12 wiz 217: <div class="titlepage"><div><div><h3 class="title">
218: <a name="tested"></a>Commit only code that you have tested.</h3></div></div></div>
1.1 jschauma 219:
220: <p>
221: Make sure that your code actually works as expected, by
222: compiling and running the code that is affected by your change
223: with your system's tools. If you changed a man page, make sure
224: that groff/nroff creates the formatted man page you expect.
225: </p>
226: <p>
227: For normal commits (to the trunk), test that your code works
1.31 kano 228: on -current. Prior to requesting a pull-up to a branch, test
1.1 jschauma 229: the very changes you will request from releng on the respective
230: release branch.
231: </p>
1.45 pooka 232: <p>
233: Run all relevant tests from
234: <code class="filename">/usr/tests</code> or
235: ideally the whole test suite. The logs of the automated
236: test runs are currently available
237: <a class="ulink" href="http://www.gson.org/netbsd/bugs/build/" target="_top">here</a>.
238: Long-term regressions (build breakage or failing tests)
239: are not acceptable and changes causing such will be backed
240: out if the regressions are not addressed.
241: </p>
1.1 jschauma 242: </div>
243: </li>
1.48 spz 244: <li class="listitem">
1.55 tron 245: <div class="sect2">
1.12 wiz 246: <div class="titlepage"><div><div><h3 class="title">
247: <a name="group"></a>Group commits together that are part of the same fix.</h3></div></div></div>
1.1 jschauma 248:
249: <p>
250: Rototilling a make variable that affects 50 Makefiles should get
251: one commit for all of them together.
252: </p>
253: </div>
254: </li>
1.48 spz 255: <li class="listitem">
1.55 tron 256: <div class="sect2">
1.12 wiz 257: <div class="titlepage"><div><div><h3 class="title">
258: <a name="separate"></a>Each commit should be a separate patch/fix/addition/etc.</h3></div></div></div>
1.1 jschauma 259:
260: <p>
261: Don't fix 3 bugs with the same commit and roll that into
262: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
263: makes life infinitely easier for releng to pull up fixes since
264: often not everything applies to a given branch.
265: </p>
266: </div>
267: </li>
1.48 spz 268: <li class="listitem">
1.55 tron 269: <div class="sect2">
1.12 wiz 270: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 271: <a name="dont-mix"></a>
272: Do not mix functionality or bug-fix patches with
273: whitespace/layout updates.
1.12 wiz 274: </h3></div></div></div>
1.1 jschauma 275:
276: <p>
277: Do those separately (apart from the general requirement that
278: changes be made in such a way that it is easy to discern what
279: each fix did, as described in item 6, there will be pullup
280: issues with largely changed files from trunk->branch when
281: mixing whitespace with functionality fixes).
282: </p>
283: </div>
284: </li>
1.48 spz 285: <li class="listitem">
1.55 tron 286: <div class="sect2">
1.12 wiz 287: <div class="titlepage"><div><div><h3 class="title">
1.46 pooka 288: <a name="document"></a>Clearly document the reasons for your changes in
289: the commit log.</h3></div></div></div>
1.1 jschauma 290:
291: <p>
1.46 pooka 292: Detail to some degree what was changed and why. This
293: doesn't need to be a code review/walkthrough but it should
294: be informative to someone reading the log and looking
295: over the diff in 6 months. The focus should be on "why"
296: since the target audience reading the logs can usually
297: figure out "what" from looking the diffs. As an exercise,
298: consider the difference of usefulness between "set i to
299: 1" and "initialize iterator correctly to fix a rarely
300: triggering bug in memory handling".
301: </p>
302:
303: <p>
304: Also, "fixed some stuff" or "cvs-1.10.0" isn't informative
305: whereas the following example is:
1.1 jschauma 306: </p>
307: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
308: <h3 class="title"></h3>
309: "Print useful line number on error while executing .for directive."
310: </div>
311: <p>
1.32 heinz 312: If your change fixes a PR, document it with an appropriate
1.48 spz 313: message. Using the template <span class="quote">“<span class="quote">PR category/bug-id</span>”</span> in
1.32 heinz 314: your commit message will also append it to the respective problem
315: report in our bug database:
1.1 jschauma 316: </p>
317: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
318: <h3 class="title"></h3>
319: "Closes PR bin/6666"
320: </div>
321: <p>
322: If your code has been reviewed by someone else, document this:
323: </p>
324: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
325: <h3 class="title"></h3>
326: "Reviewed by <mrg>"
327: </div>
328: <p>
329: (Please note that a good commit log doesn't relieve the need
330: for good documentation in the program itself.)
331: </p>
332: </div>
333: </li>
1.48 spz 334: <li class="listitem">
1.55 tron 335: <div class="sect2">
1.12 wiz 336: <div class="titlepage"><div><div><h3 class="title">
337: <a name="credit"></a>Give proper credit.</h3></div></div></div>
1.1 jschauma 338:
339: <p>
340: If you commit code that had been submitted in a PR, give
341: proper credit, like:
342: </p>
343: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
344: <h3 class="title"></h3>
345: "Code submitted in PR lib/393939 by Joe Doe"
346: </div>
347: <p>
348: Since the commit messages will eventually appear on the
349: source-changes mailing list which is also available via web,
350: specifying the e-mail addresses of the PR submitter should
351: generally be avoided.
352: </p>
353: <p>
354: If you took code from an other Open Source Project, give
355: credit, like:
356: </p>
357: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
358: <h3 class="title"></h3>
359: "From FreeBSD"
360: </div>
361: </div>
362: </li>
1.48 spz 363: <li class="listitem">
1.55 tron 364: <div class="sect2">
1.12 wiz 365: <div class="titlepage"><div><div><h3 class="title">
366: <a name="revert"></a>Do not revert other developer's commits.</h3></div></div></div>
1.1 jschauma 367:
368: <p>
369: If you do not agree with another developer's commit, do not
370: revert it on your own. Contact the other developer and explain
1.47 spz 371: to him or her the issues you have with the commit in question.
372: Ask the other developer to back out the changes instead of
373: doing it yourself.
1.1 jschauma 374: </p>
375: <p>
1.70 leot 376: If no agreement can be reached, contact the Core Team
377: <core@NetBSD.org>, which
1.1 jschauma 378: will serve as mediation authority.
379: </p>
380: </div>
381: </li>
382: </ol></div>
383:
384: </div>
1.34 dsieger 385: </div></div></div>
386: <div class="navfoot"></div>
1.43 mishka 387: <div id="footer"><div id="footerContent"><center>
1.65 maya 388: <span class="footfeed"><a href="//www.NetBSD.org/cgi-bin/feedback.cgi">
1.34 dsieger 389: Contact</a> |
1.40 kano 390: </span><span class="footcopy"><a href="../about/disclaimer.html">
1.34 dsieger 391: Disclaimer</a> |
1.1 jschauma 392:
1.69 jakllsch 393: <span class="copyright">Copyright © 1994-2018 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
1.34 dsieger 394: Foundation, Inc.</span>
1.43 mishka 395: </center></div></div>
1.1 jschauma 396: </div></body>
397: </html>
CVSweb <webmaster@jp.NetBSD.org>