Annotation of htdocs/developers/commit-guidelines.html, revision 1.103
1.89 nia 1: <!DOCTYPE html>
1.98 martin 2: <html lang="en">
1.1 jschauma 3: <head>
1.101 maya 4: <meta charset="utf-8">
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.99 andvar 18: <body class="website"><div class="webpage" id="developers-commit-guidelines">
19: <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.102 leot 82: <li><a href="//cvsweb.NetBSD.org/">
1.83 maya 83: CVSWeb</a></li>
1.65 maya 84: <li><a href="//nxr.NetBSD.org/">
1.50 jym 85: Cross-reference</a></li>
1.65 maya 86: <li><a href="//releng.NetBSD.org/">
1.50 jym 87: Release engineering</a></li>
1.65 maya 88: <li><a href="//wiki.NetBSD.org/projects/">
1.50 jym 89: Projects list</a></li>
90: </ul>
91: </li>
92: </ul>
1.34 dsieger 93: </div>
1.73 maya 94: <div id="content"><div id="mainContent" class="fullWidth"><div class="rowOfBoxes">
1.34 dsieger 95: <h1>NetBSD Commit Guidelines</h1>
1.99 andvar 96: <div class="sect1" id="guidelines">
97: <div class="titlepage"><h2 class="titlepage">
1.1 jschauma 98: The following Commit Guidelines define the Project's standards for making
99: commits to the source tree:
1.99 andvar 100: </h2></div>
1.1 jschauma 101:
102:
103:
1.48 spz 104: <div class="orderedlist"><ol class="orderedlist" type="1">
105: <li class="listitem">
1.99 andvar 106: <div class="sect2" id="know-thy-code">
107: <div class="titlepage"><h3 class="titlepage">Commit only code you are familiar with.</h3></div>
1.1 jschauma 108:
109: <p>
110: If you are not sure if the code you plan to commit is acceptable
111: (e. g. when taking code that was submitted with a problem report),
112: ask a developer who is familiar with that part of the system for
113: review. If you're new to the Project, check with your sponsor.
114: </p>
115: </div>
116: </li>
1.48 spz 117: <li class="listitem">
1.99 andvar 118: <div class="sect2" id="tainted">
119: <div class="titlepage"><h3 class="titlepage">Do not commit tainted code to the repository.</h3></div>
1.1 jschauma 120:
121: <p>
122: If you commit code that was not written by yourself, double check
123: that the license on that code permits import into the NetBSD source
124: repository, and permits free distribution. Check with the author(s)
125: of the code, make sure that they were the sole author of the code
126: and verify with them that they did not copy any other code.
127: </p>
1.93 riastrad 128: <p>
129: Code generated by a large language model or similar technology,
1.94 gutterid 130: such as GitHub/Microsoft's Copilot, OpenAI's ChatGPT,
1.93 riastrad 131: or Facebook/Meta's Code Llama, is presumed to be tainted
132: code, and must not be committed without prior written approval
133: by core.
134: </p>
1.1 jschauma 135: </div>
136: </li>
1.48 spz 137: <li class="listitem">
1.99 andvar 138: <div class="sect2" id="repository">
139: <div class="titlepage"><h3 class="titlepage">Do not commit code from foreign trees.</h3></div>
1.29 jschauma 140:
141: <p>
142: Do not commit code from a tree checked out from anywhere but from
143: cvs.NetBSD.org. Note that all developers have access to the private
1.41 dsieger 144: <a class="ulink" href="restricted.html#rsync" target="_top">rsync-over-ssh service on
1.29 jschauma 145: cvs.NetBSD.org</a>.
146: </p>
147: </div>
148: </li>
1.48 spz 149: <li class="listitem">
1.99 andvar 150: <div class="sect2" id="intrusive">
151: <div class="titlepage"><h3 class="titlepage">
1.1 jschauma 152: The more intrusive your changes are the higher is the level of
153: required prior approval.
1.99 andvar 154: </h3></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.99 andvar 188: <div class="sect2" id="tested">
189: <div class="titlepage"><h3 class="titlepage">Commit only code that you have tested.</h3></div>
1.1 jschauma 190:
191: <p>
192: Make sure that your code actually works as expected, by
193: compiling and running the code that is affected by your change
194: with your system's tools. If you changed a man page, make sure
195: that groff/nroff creates the formatted man page you expect.
196: </p>
197: <p>
198: For normal commits (to the trunk), test that your code works
1.31 kano 199: on -current. Prior to requesting a pull-up to a branch, test
1.1 jschauma 200: the very changes you will request from releng on the respective
201: release branch.
202: </p>
1.45 pooka 203: <p>
204: Run all relevant tests from
205: <code class="filename">/usr/tests</code> or
1.95 riastrad 206: ideally the whole test suite.
207: Check the
208: <a class="ulink" href="//releng.NetBSD.org/cgi-bin/builds.cgi" target="_top">daily
209: builds</a>
210: and the
211: <a class="ulink" href="//releng.NetBSD.org/test-results.html" target="_top">automated
212: test runs</a>.
1.45 pooka 213: Long-term regressions (build breakage or failing tests)
214: are not acceptable and changes causing such will be backed
215: out if the regressions are not addressed.
216: </p>
1.1 jschauma 217: </div>
218: </li>
1.48 spz 219: <li class="listitem">
1.99 andvar 220: <div class="sect2" id="group">
221: <div class="titlepage"><h3 class="titlepage">Group commits together that are part of the same fix.</h3></div>
1.1 jschauma 222:
223: <p>
224: Rototilling a make variable that affects 50 Makefiles should get
225: one commit for all of them together.
226: </p>
227: </div>
228: </li>
1.48 spz 229: <li class="listitem">
1.99 andvar 230: <div class="sect2" id="separate">
231: <div class="titlepage"><h3 class="titlepage">Each commit should be a separate patch/fix/addition/etc.</h3></div>
1.1 jschauma 232:
233: <p>
234: Don't fix 3 bugs with the same commit and roll that into
235: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
236: makes life infinitely easier for releng to pull up fixes since
237: often not everything applies to a given branch.
238: </p>
239: </div>
240: </li>
1.48 spz 241: <li class="listitem">
1.99 andvar 242: <div class="sect2" id="dont-mix">
243: <div class="titlepage"><h3 class="titlepage">
1.1 jschauma 244: Do not mix functionality or bug-fix patches with
245: whitespace/layout updates.
1.99 andvar 246: </h3></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.99 andvar 258: <div class="sect2" id="document">
259: <div class="titlepage"><h3 class="titlepage">Clearly document the reasons for your changes in
260: the commit log.</h3></div>
1.1 jschauma 261:
262: <p>
1.46 pooka 263: Detail to some degree what was changed and why. This
264: doesn't need to be a code review/walkthrough but it should
265: be informative to someone reading the log and looking
266: over the diff in 6 months. The focus should be on "why"
267: since the target audience reading the logs can usually
268: figure out "what" from looking the diffs. As an exercise,
269: consider the difference of usefulness between "set i to
270: 1" and "initialize iterator correctly to fix a rarely
271: triggering bug in memory handling".
272: </p>
273:
274: <p>
275: Also, "fixed some stuff" or "cvs-1.10.0" isn't informative
276: whereas the following example is:
1.1 jschauma 277: </p>
278: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
279: <h3 class="title"></h3>
280: "Print useful line number on error while executing .for directive."
281: </div>
282: <p>
1.32 heinz 283: If your change fixes a PR, document it with an appropriate
1.98 martin 284: message. Using the template <span class="quote">“<span class="quote">PR category/bug-id</span>”</span> in
1.32 heinz 285: your commit message will also append it to the respective problem
286: report in our bug database:
1.1 jschauma 287: </p>
288: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
289: <h3 class="title"></h3>
290: "Closes PR bin/6666"
291: </div>
292: <p>
293: If your code has been reviewed by someone else, document this:
294: </p>
295: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
296: <h3 class="title"></h3>
297: "Reviewed by <mrg>"
298: </div>
299: <p>
300: (Please note that a good commit log doesn't relieve the need
301: for good documentation in the program itself.)
302: </p>
303: </div>
304: </li>
1.48 spz 305: <li class="listitem">
1.99 andvar 306: <div class="sect2" id="credit">
307: <div class="titlepage"><h3 class="titlepage">Give proper credit.</h3></div>
1.1 jschauma 308:
309: <p>
310: If you commit code that had been submitted in a PR, give
311: proper credit, like:
312: </p>
313: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
314: <h3 class="title"></h3>
315: "Code submitted in PR lib/393939 by Joe Doe"
316: </div>
317: <p>
318: Since the commit messages will eventually appear on the
319: source-changes mailing list which is also available via web,
320: specifying the e-mail addresses of the PR submitter should
321: generally be avoided.
322: </p>
323: <p>
324: If you took code from an other Open Source Project, give
325: credit, like:
326: </p>
327: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
328: <h3 class="title"></h3>
329: "From FreeBSD"
330: </div>
331: </div>
332: </li>
1.48 spz 333: <li class="listitem">
1.99 andvar 334: <div class="sect2" id="revert">
335: <div class="titlepage"><h3 class="titlepage">Do not revert other developer's commits.</h3></div>
1.1 jschauma 336:
337: <p>
338: If you do not agree with another developer's commit, do not
339: revert it on your own. Contact the other developer and explain
1.47 spz 340: to him or her the issues you have with the commit in question.
341: Ask the other developer to back out the changes instead of
342: doing it yourself.
1.1 jschauma 343: </p>
344: <p>
1.70 leot 345: If no agreement can be reached, contact the Core Team
346: <core@NetBSD.org>, which
1.1 jschauma 347: will serve as mediation authority.
348: </p>
349: </div>
350: </li>
351: </ol></div>
352:
353: </div>
1.34 dsieger 354: </div></div></div>
355: <div class="navfoot"></div>
1.99 andvar 356: <div id="footer"><div id="footerContent">
357: <span class="footfeed"><a href="//www.NetBSD.org/cgi-bin/feedback.cgi">
1.34 dsieger 358: Contact</a> |
1.40 kano 359: </span><span class="footcopy"><a href="../about/disclaimer.html">
1.34 dsieger 360: Disclaimer</a> |
1.1 jschauma 361:
1.100 leot 362: <span class="copyright">Copyright © 1994-2026 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
1.99 andvar 363: Foundation, Inc.</span>
364: </div></div>
1.1 jschauma 365: </div></body>
366: </html>
CVSweb <webmaster@jp.NetBSD.org>