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