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