Annotation of htdocs/developers/commit-guidelines.html, revision 1.100
1.89 nia 1: <!DOCTYPE html>
1.98 martin 2: <html lang="en">
1.1 jschauma 3: <head>
1.98 martin 4: <meta http-equiv="Content-Type" content="text/html; 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.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.99 andvar 98: <div class="sect1" id="guidelines">
99: <div class="titlepage"><h2 class="titlepage">
1.1 jschauma 100: The following Commit Guidelines define the Project's standards for making
101: commits to the source tree:
1.99 andvar 102: </h2></div>
1.1 jschauma 103:
104:
105:
1.48 spz 106: <div class="orderedlist"><ol class="orderedlist" type="1">
107: <li class="listitem">
1.99 andvar 108: <div class="sect2" id="know-thy-code">
109: <div class="titlepage"><h3 class="titlepage">Commit only code you are familiar with.</h3></div>
1.1 jschauma 110:
111: <p>
112: If you are not sure if the code you plan to commit is acceptable
113: (e. g. when taking code that was submitted with a problem report),
114: ask a developer who is familiar with that part of the system for
115: review. If you're new to the Project, check with your sponsor.
116: </p>
117: </div>
118: </li>
1.48 spz 119: <li class="listitem">
1.99 andvar 120: <div class="sect2" id="tainted">
121: <div class="titlepage"><h3 class="titlepage">Do not commit tainted code to the repository.</h3></div>
1.1 jschauma 122:
123: <p>
124: If you commit code that was not written by yourself, double check
125: that the license on that code permits import into the NetBSD source
126: repository, and permits free distribution. Check with the author(s)
127: of the code, make sure that they were the sole author of the code
128: and verify with them that they did not copy any other code.
129: </p>
1.93 riastrad 130: <p>
131: Code generated by a large language model or similar technology,
1.94 gutterid 132: such as GitHub/Microsoft's Copilot, OpenAI's ChatGPT,
1.93 riastrad 133: or Facebook/Meta's Code Llama, is presumed to be tainted
134: code, and must not be committed without prior written approval
135: by core.
136: </p>
1.1 jschauma 137: </div>
138: </li>
1.48 spz 139: <li class="listitem">
1.99 andvar 140: <div class="sect2" id="repository">
141: <div class="titlepage"><h3 class="titlepage">Do not commit code from foreign trees.</h3></div>
1.29 jschauma 142:
143: <p>
144: Do not commit code from a tree checked out from anywhere but from
145: cvs.NetBSD.org. Note that all developers have access to the private
1.41 dsieger 146: <a class="ulink" href="restricted.html#rsync" target="_top">rsync-over-ssh service on
1.29 jschauma 147: cvs.NetBSD.org</a>.
148: </p>
149: </div>
150: </li>
1.48 spz 151: <li class="listitem">
1.99 andvar 152: <div class="sect2" id="intrusive">
153: <div class="titlepage"><h3 class="titlepage">
1.1 jschauma 154: The more intrusive your changes are the higher is the level of
155: required prior approval.
1.99 andvar 156: </h3></div>
1.1 jschauma 157:
1.55 tron 158: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.48 spz 159: <li class="listitem">
1.1 jschauma 160: <p>
161: "Obvious" fixes can be committed without any prior discussion
162: or review. (The definition of "obvious" in the GCC Project is:
163: "could not possibly cause anyone to object." We adopt this
164: definition here)
165: </p>
166: </li>
1.48 spz 167: <li class="listitem">
1.1 jschauma 168: <p>
169: All other (i. e. "non-obvious") fixes <span class="emphasis"><em>should</em></span>
170: have a review.
171: </p>
172: </li>
1.48 spz 173: <li class="listitem">
1.1 jschauma 174: <p>
175: Implementing (significant) new features requires a prior
176: discussion on an appropriate technical mailing list.
177: </p>
178: </li>
1.48 spz 179: <li class="listitem">
1.1 jschauma 180: <p>
1.46 pooka 181: Adding a completely new package (e.g. openldap) requires
182: prior discussion on a mailing list <span class="emphasis"><em>and</em></span>
183: approval from core.
1.1 jschauma 184: </p>
185: </li>
186: </ul></div>
187: </div>
188: </li>
1.48 spz 189: <li class="listitem">
1.99 andvar 190: <div class="sect2" id="tested">
191: <div class="titlepage"><h3 class="titlepage">Commit only code that you have tested.</h3></div>
1.1 jschauma 192:
193: <p>
194: Make sure that your code actually works as expected, by
195: compiling and running the code that is affected by your change
196: with your system's tools. If you changed a man page, make sure
197: that groff/nroff creates the formatted man page you expect.
198: </p>
199: <p>
200: For normal commits (to the trunk), test that your code works
1.31 kano 201: on -current. Prior to requesting a pull-up to a branch, test
1.1 jschauma 202: the very changes you will request from releng on the respective
203: release branch.
204: </p>
1.45 pooka 205: <p>
206: Run all relevant tests from
207: <code class="filename">/usr/tests</code> or
1.95 riastrad 208: ideally the whole test suite.
209: Check the
210: <a class="ulink" href="//releng.NetBSD.org/cgi-bin/builds.cgi" target="_top">daily
211: builds</a>
212: and the
213: <a class="ulink" href="//releng.NetBSD.org/test-results.html" target="_top">automated
214: test runs</a>.
1.45 pooka 215: Long-term regressions (build breakage or failing tests)
216: are not acceptable and changes causing such will be backed
217: out if the regressions are not addressed.
218: </p>
1.1 jschauma 219: </div>
220: </li>
1.48 spz 221: <li class="listitem">
1.99 andvar 222: <div class="sect2" id="group">
223: <div class="titlepage"><h3 class="titlepage">Group commits together that are part of the same fix.</h3></div>
1.1 jschauma 224:
225: <p>
226: Rototilling a make variable that affects 50 Makefiles should get
227: one commit for all of them together.
228: </p>
229: </div>
230: </li>
1.48 spz 231: <li class="listitem">
1.99 andvar 232: <div class="sect2" id="separate">
233: <div class="titlepage"><h3 class="titlepage">Each commit should be a separate patch/fix/addition/etc.</h3></div>
1.1 jschauma 234:
235: <p>
236: Don't fix 3 bugs with the same commit and roll that into
237: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
238: makes life infinitely easier for releng to pull up fixes since
239: often not everything applies to a given branch.
240: </p>
241: </div>
242: </li>
1.48 spz 243: <li class="listitem">
1.99 andvar 244: <div class="sect2" id="dont-mix">
245: <div class="titlepage"><h3 class="titlepage">
1.1 jschauma 246: Do not mix functionality or bug-fix patches with
247: whitespace/layout updates.
1.99 andvar 248: </h3></div>
1.1 jschauma 249:
250: <p>
251: Do those separately (apart from the general requirement that
252: changes be made in such a way that it is easy to discern what
253: each fix did, as described in item 6, there will be pullup
254: issues with largely changed files from trunk->branch when
255: mixing whitespace with functionality fixes).
256: </p>
257: </div>
258: </li>
1.48 spz 259: <li class="listitem">
1.99 andvar 260: <div class="sect2" id="document">
261: <div class="titlepage"><h3 class="titlepage">Clearly document the reasons for your changes in
262: the commit log.</h3></div>
1.1 jschauma 263:
264: <p>
1.46 pooka 265: Detail to some degree what was changed and why. This
266: doesn't need to be a code review/walkthrough but it should
267: be informative to someone reading the log and looking
268: over the diff in 6 months. The focus should be on "why"
269: since the target audience reading the logs can usually
270: figure out "what" from looking the diffs. As an exercise,
271: consider the difference of usefulness between "set i to
272: 1" and "initialize iterator correctly to fix a rarely
273: triggering bug in memory handling".
274: </p>
275:
276: <p>
277: Also, "fixed some stuff" or "cvs-1.10.0" isn't informative
278: whereas the following example is:
1.1 jschauma 279: </p>
280: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
281: <h3 class="title"></h3>
282: "Print useful line number on error while executing .for directive."
283: </div>
284: <p>
1.32 heinz 285: If your change fixes a PR, document it with an appropriate
1.98 martin 286: message. Using the template <span class="quote">“<span class="quote">PR category/bug-id</span>”</span> in
1.32 heinz 287: your commit message will also append it to the respective problem
288: report in our bug database:
1.1 jschauma 289: </p>
290: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
291: <h3 class="title"></h3>
292: "Closes PR bin/6666"
293: </div>
294: <p>
295: If your code has been reviewed by someone else, document this:
296: </p>
297: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
298: <h3 class="title"></h3>
299: "Reviewed by <mrg>"
300: </div>
301: <p>
302: (Please note that a good commit log doesn't relieve the need
303: for good documentation in the program itself.)
304: </p>
305: </div>
306: </li>
1.48 spz 307: <li class="listitem">
1.99 andvar 308: <div class="sect2" id="credit">
309: <div class="titlepage"><h3 class="titlepage">Give proper credit.</h3></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.99 andvar 336: <div class="sect2" id="revert">
337: <div class="titlepage"><h3 class="titlepage">Do not revert other developer's commits.</h3></div>
1.1 jschauma 338:
339: <p>
340: If you do not agree with another developer's commit, do not
341: revert it on your own. Contact the other developer and explain
1.47 spz 342: to him or her the issues you have with the commit in question.
343: Ask the other developer to back out the changes instead of
344: doing it yourself.
1.1 jschauma 345: </p>
346: <p>
1.70 leot 347: If no agreement can be reached, contact the Core Team
348: <core@NetBSD.org>, which
1.1 jschauma 349: will serve as mediation authority.
350: </p>
351: </div>
352: </li>
353: </ol></div>
354:
355: </div>
1.34 dsieger 356: </div></div></div>
357: <div class="navfoot"></div>
1.99 andvar 358: <div id="footer"><div id="footerContent">
359: <span class="footfeed"><a href="//www.NetBSD.org/cgi-bin/feedback.cgi">
1.34 dsieger 360: Contact</a> |
1.40 kano 361: </span><span class="footcopy"><a href="../about/disclaimer.html">
1.34 dsieger 362: Disclaimer</a> |
1.1 jschauma 363:
1.100 ! leot 364: <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 365: Foundation, Inc.</span>
366: </div></div>
1.1 jschauma 367: </div></body>
368: </html>
CVSweb <webmaster@jp.NetBSD.org>