Annotation of htdocs/developers/commit-guidelines.html, revision 1.97
1.89 nia 1: <!DOCTYPE html>
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>
1.97 ! andvar 16: <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
1.1 jschauma 17: </head>
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>
1.93 riastrad 133: <p>
134: Code generated by a large language model or similar technology,
1.94 gutterid 135: such as GitHub/Microsoft's Copilot, OpenAI's ChatGPT,
1.93 riastrad 136: or Facebook/Meta's Code Llama, is presumed to be tainted
137: code, and must not be committed without prior written approval
138: by core.
139: </p>
1.1 jschauma 140: </div>
141: </li>
1.48 spz 142: <li class="listitem">
1.55 tron 143: <div class="sect2">
1.12 wiz 144: <div class="titlepage"><div><div><h3 class="title">
1.29 jschauma 145: <a name="repository"></a>Do not commit code from foreign trees.</h3></div></div></div>
146:
147: <p>
148: Do not commit code from a tree checked out from anywhere but from
149: cvs.NetBSD.org. Note that all developers have access to the private
1.41 dsieger 150: <a class="ulink" href="restricted.html#rsync" target="_top">rsync-over-ssh service on
1.29 jschauma 151: cvs.NetBSD.org</a>.
152: </p>
153: </div>
154: </li>
1.48 spz 155: <li class="listitem">
1.55 tron 156: <div class="sect2">
1.29 jschauma 157: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 158: <a name="intrusive"></a>
159: The more intrusive your changes are the higher is the level of
160: required prior approval.
1.12 wiz 161: </h3></div></div></div>
1.1 jschauma 162:
1.55 tron 163: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.48 spz 164: <li class="listitem">
1.1 jschauma 165: <p>
166: "Obvious" fixes can be committed without any prior discussion
167: or review. (The definition of "obvious" in the GCC Project is:
168: "could not possibly cause anyone to object." We adopt this
169: definition here)
170: </p>
171: </li>
1.48 spz 172: <li class="listitem">
1.1 jschauma 173: <p>
174: All other (i. e. "non-obvious") fixes <span class="emphasis"><em>should</em></span>
175: have a review.
176: </p>
177: </li>
1.48 spz 178: <li class="listitem">
1.1 jschauma 179: <p>
180: Implementing (significant) new features requires a prior
181: discussion on an appropriate technical mailing list.
182: </p>
183: </li>
1.48 spz 184: <li class="listitem">
1.1 jschauma 185: <p>
1.46 pooka 186: Adding a completely new package (e.g. openldap) requires
187: prior discussion on a mailing list <span class="emphasis"><em>and</em></span>
188: approval from core.
1.1 jschauma 189: </p>
190: </li>
191: </ul></div>
192: </div>
193: </li>
1.48 spz 194: <li class="listitem">
1.55 tron 195: <div class="sect2">
1.12 wiz 196: <div class="titlepage"><div><div><h3 class="title">
197: <a name="tested"></a>Commit only code that you have tested.</h3></div></div></div>
1.1 jschauma 198:
199: <p>
200: Make sure that your code actually works as expected, by
201: compiling and running the code that is affected by your change
202: with your system's tools. If you changed a man page, make sure
203: that groff/nroff creates the formatted man page you expect.
204: </p>
205: <p>
206: For normal commits (to the trunk), test that your code works
1.31 kano 207: on -current. Prior to requesting a pull-up to a branch, test
1.1 jschauma 208: the very changes you will request from releng on the respective
209: release branch.
210: </p>
1.45 pooka 211: <p>
212: Run all relevant tests from
213: <code class="filename">/usr/tests</code> or
1.95 riastrad 214: ideally the whole test suite.
215: Check the
216: <a class="ulink" href="//releng.NetBSD.org/cgi-bin/builds.cgi" target="_top">daily
217: builds</a>
218: and the
219: <a class="ulink" href="//releng.NetBSD.org/test-results.html" target="_top">automated
220: test runs</a>.
1.45 pooka 221: Long-term regressions (build breakage or failing tests)
222: are not acceptable and changes causing such will be backed
223: out if the regressions are not addressed.
224: </p>
1.1 jschauma 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="group"></a>Group commits together that are part of the same fix.</h3></div></div></div>
1.1 jschauma 231:
232: <p>
233: Rototilling a make variable that affects 50 Makefiles should get
234: one commit for all of them together.
235: </p>
236: </div>
237: </li>
1.48 spz 238: <li class="listitem">
1.55 tron 239: <div class="sect2">
1.12 wiz 240: <div class="titlepage"><div><div><h3 class="title">
241: <a name="separate"></a>Each commit should be a separate patch/fix/addition/etc.</h3></div></div></div>
1.1 jschauma 242:
243: <p>
244: Don't fix 3 bugs with the same commit and roll that into
245: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
246: makes life infinitely easier for releng to pull up fixes since
247: often not everything applies to a given branch.
248: </p>
249: </div>
250: </li>
1.48 spz 251: <li class="listitem">
1.55 tron 252: <div class="sect2">
1.12 wiz 253: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 254: <a name="dont-mix"></a>
255: Do not mix functionality or bug-fix patches with
256: whitespace/layout updates.
1.12 wiz 257: </h3></div></div></div>
1.1 jschauma 258:
259: <p>
260: Do those separately (apart from the general requirement that
261: changes be made in such a way that it is easy to discern what
262: each fix did, as described in item 6, there will be pullup
263: issues with largely changed files from trunk->branch when
264: mixing whitespace with functionality fixes).
265: </p>
266: </div>
267: </li>
1.48 spz 268: <li class="listitem">
1.55 tron 269: <div class="sect2">
1.12 wiz 270: <div class="titlepage"><div><div><h3 class="title">
1.46 pooka 271: <a name="document"></a>Clearly document the reasons for your changes in
272: the commit log.</h3></div></div></div>
1.1 jschauma 273:
274: <p>
1.46 pooka 275: Detail to some degree what was changed and why. This
276: doesn't need to be a code review/walkthrough but it should
277: be informative to someone reading the log and looking
278: over the diff in 6 months. The focus should be on "why"
279: since the target audience reading the logs can usually
280: figure out "what" from looking the diffs. As an exercise,
281: consider the difference of usefulness between "set i to
282: 1" and "initialize iterator correctly to fix a rarely
283: triggering bug in memory handling".
284: </p>
285:
286: <p>
287: Also, "fixed some stuff" or "cvs-1.10.0" isn't informative
288: whereas the following example is:
1.1 jschauma 289: </p>
290: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
291: <h3 class="title"></h3>
292: "Print useful line number on error while executing .for directive."
293: </div>
294: <p>
1.32 heinz 295: If your change fixes a PR, document it with an appropriate
1.48 spz 296: message. Using the template <span class="quote">“<span class="quote">PR category/bug-id</span>”</span> in
1.32 heinz 297: your commit message will also append it to the respective problem
298: report in our bug database:
1.1 jschauma 299: </p>
300: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
301: <h3 class="title"></h3>
302: "Closes PR bin/6666"
303: </div>
304: <p>
305: If your code has been reviewed by someone else, document this:
306: </p>
307: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
308: <h3 class="title"></h3>
309: "Reviewed by <mrg>"
310: </div>
311: <p>
312: (Please note that a good commit log doesn't relieve the need
313: for good documentation in the program itself.)
314: </p>
315: </div>
316: </li>
1.48 spz 317: <li class="listitem">
1.55 tron 318: <div class="sect2">
1.12 wiz 319: <div class="titlepage"><div><div><h3 class="title">
320: <a name="credit"></a>Give proper credit.</h3></div></div></div>
1.1 jschauma 321:
322: <p>
323: If you commit code that had been submitted in a PR, give
324: proper credit, like:
325: </p>
326: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
327: <h3 class="title"></h3>
328: "Code submitted in PR lib/393939 by Joe Doe"
329: </div>
330: <p>
331: Since the commit messages will eventually appear on the
332: source-changes mailing list which is also available via web,
333: specifying the e-mail addresses of the PR submitter should
334: generally be avoided.
335: </p>
336: <p>
337: If you took code from an other Open Source Project, give
338: credit, like:
339: </p>
340: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
341: <h3 class="title"></h3>
342: "From FreeBSD"
343: </div>
344: </div>
345: </li>
1.48 spz 346: <li class="listitem">
1.55 tron 347: <div class="sect2">
1.12 wiz 348: <div class="titlepage"><div><div><h3 class="title">
349: <a name="revert"></a>Do not revert other developer's commits.</h3></div></div></div>
1.1 jschauma 350:
351: <p>
352: If you do not agree with another developer's commit, do not
353: revert it on your own. Contact the other developer and explain
1.47 spz 354: to him or her the issues you have with the commit in question.
355: Ask the other developer to back out the changes instead of
356: doing it yourself.
1.1 jschauma 357: </p>
358: <p>
1.70 leot 359: If no agreement can be reached, contact the Core Team
360: <core@NetBSD.org>, which
1.1 jschauma 361: will serve as mediation authority.
362: </p>
363: </div>
364: </li>
365: </ol></div>
366:
367: </div>
1.34 dsieger 368: </div></div></div>
369: <div class="navfoot"></div>
1.43 mishka 370: <div id="footer"><div id="footerContent"><center>
1.65 maya 371: <span class="footfeed"><a href="//www.NetBSD.org/cgi-bin/feedback.cgi">
1.34 dsieger 372: Contact</a> |
1.40 kano 373: </span><span class="footcopy"><a href="../about/disclaimer.html">
1.34 dsieger 374: Disclaimer</a> |
1.1 jschauma 375:
1.96 maya 376: <span class="copyright">Copyright © 1994-2025 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
1.34 dsieger 377: Foundation, Inc.</span>
1.43 mishka 378: </center></div></div>
1.1 jschauma 379: </div></body>
380: </html>
CVSweb <webmaster@jp.NetBSD.org>