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