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