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