Annotation of htdocs/developers/commit-guidelines.html, revision 1.45
1.1 jschauma 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
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>
18: <div id="header">
19: <div class="topNavigation">
1.37 dsieger 20: <span>» </span><a href="../docs/guide/en/">
21: The Guide</a> |
1.34 dsieger 22: <a href="http://man.NetBSD.org/">Manual pages</a> |
1.39 kano 23: <a href="../mailinglists/">
1.37 dsieger 24: Mailing lists</a> and
1.34 dsieger 25: <a href="http://mail-index.NetBSD.org/">Archives</a> |
26: <a href="http://cvsweb.NetBSD.org/">CVS repository</a> |
1.37 dsieger 27: <a href="http://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd">Report</a>
28: or
1.40 kano 29: <a href="../support/query-pr.html">
30: query</a> a bug |
1.37 dsieger 31: <a href="../docs/software/packages.html">
32: Software Packages
33: </a>
1.34 dsieger 34: </div>
35: <div class="centralHeader">
1.37 dsieger 36: <a href="../"><img alt="[NetBSD Logo]" width="506" height="90" src="../images/NetBSD-headerlogo.png"></a><div class="headerTools"><div id="headerSearch"><form method="get" action="http://www.google.com/custom">
1.35 dsieger 37: <input class="whiteOnBlack" type="text" name="q" onfocus="if(this.value==this.defaultValue ) this.value='';" size="12" maxlength="255" value="Search"><input type="hidden" name="cof" value="L:http://www.NetBSD.org/images/NetBSD-smaller.png;LH:200;LW:200;AH:center;AWFID:4f6b0499f0f58d2c;"><input type="hidden" name="domains" value="NetBSD.org"><input type="hidden" name="sitesearch" value="www.NetBSD.org"><input type="submit" value="Search">
1.34 dsieger 38: </form></div></div>
39: </div>
40: <div class="navBar">
1.37 dsieger 41: <span class="doNotDisplay">
42: Navigation:
43: </span><a href="../">
44: Home</a> |
45: <a href="../about/">
46: About</a> |
1.42 hubertf 47: <a href="../gallery/">
48: Gallery</a> |
1.37 dsieger 49: <a href="../releases/">
50: Download</a> |
51: <a href="../docs/">
52: Documentation</a> |
53: <a href="../support/">
54: Support</a> |
55: <a href="../community/">
56: Community</a> |
57: <a href="../ports/">
58: Ports</a>
1.34 dsieger 59: </div>
60: </div>
61: <div id="content"><div class="fullWidth"><div class="rowOfBoxes">
62: <h1>NetBSD Commit Guidelines</h1>
1.45 ! pooka 63: <div class="sect1" title="The following Commit Guidelines define the Project's standards for making commits to the source tree:">
1.12 wiz 64: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.1 jschauma 65: <a name="guidelines"></a>
66: The following Commit Guidelines define the Project's standards for making
67: commits to the source tree:
1.12 wiz 68: </h2></div></div></div>
1.1 jschauma 69:
70:
71:
1.45 ! pooka 72: <div class="orderedlist"><ol class="orderedlist" type="1">
! 73: <li class="listitem">
! 74: <div class="sect2" title="Commit only code you are familiar with.">
1.12 wiz 75: <div class="titlepage"><div><div><h3 class="title">
76: <a name="know-thy-code"></a>Commit only code you are familiar with.</h3></div></div></div>
1.1 jschauma 77:
78: <p>
79: If you are not sure if the code you plan to commit is acceptable
80: (e. g. when taking code that was submitted with a problem report),
81: ask a developer who is familiar with that part of the system for
82: review. If you're new to the Project, check with your sponsor.
83: </p>
84: </div>
85: </li>
1.45 ! pooka 86: <li class="listitem">
! 87: <div class="sect2" title="Do not commit tainted code to the repository.">
1.12 wiz 88: <div class="titlepage"><div><div><h3 class="title">
89: <a name="tainted"></a>Do not commit tainted code to the repository.</h3></div></div></div>
1.1 jschauma 90:
91: <p>
92: If you commit code that was not written by yourself, double check
93: that the license on that code permits import into the NetBSD source
94: repository, and permits free distribution. Check with the author(s)
95: of the code, make sure that they were the sole author of the code
96: and verify with them that they did not copy any other code.
97: </p>
98: </div>
99: </li>
1.45 ! pooka 100: <li class="listitem">
! 101: <div class="sect2" title="Do not commit code from foreign trees.">
1.12 wiz 102: <div class="titlepage"><div><div><h3 class="title">
1.29 jschauma 103: <a name="repository"></a>Do not commit code from foreign trees.</h3></div></div></div>
104:
105: <p>
106: Do not commit code from a tree checked out from anywhere but from
107: cvs.NetBSD.org. Note that all developers have access to the private
1.41 dsieger 108: <a class="ulink" href="restricted.html#rsync" target="_top">rsync-over-ssh service on
1.29 jschauma 109: cvs.NetBSD.org</a>.
110: </p>
111: </div>
112: </li>
1.45 ! pooka 113: <li class="listitem">
! 114: <div class="sect2" title="The more intrusive your changes are the higher is the level of required prior approval.">
1.29 jschauma 115: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 116: <a name="intrusive"></a>
117: The more intrusive your changes are the higher is the level of
118: required prior approval.
1.12 wiz 119: </h3></div></div></div>
1.1 jschauma 120:
1.45 ! pooka 121: <div class="itemizedlist"><ul class="itemizedlist" type="disc">
! 122: <li class="listitem">
1.1 jschauma 123: <p>
124: "Obvious" fixes can be committed without any prior discussion
125: or review. (The definition of "obvious" in the GCC Project is:
126: "could not possibly cause anyone to object." We adopt this
127: definition here)
128: </p>
129: </li>
1.45 ! pooka 130: <li class="listitem">
1.1 jschauma 131: <p>
132: All other (i. e. "non-obvious") fixes <span class="emphasis"><em>should</em></span>
133: have a review.
134: </p>
135: </li>
1.45 ! pooka 136: <li class="listitem">
1.1 jschauma 137: <p>
138: Implementing (significant) new features requires a prior
139: discussion on an appropriate technical mailing list.
140: </p>
141: </li>
1.45 ! pooka 142: <li class="listitem">
1.1 jschauma 143: <p>
144: Changing existing interfaces in libraries or in the kernel
145: requires prior approval by Core.
146: </p>
147: </li>
148: </ul></div>
149: </div>
150: </li>
1.45 ! pooka 151: <li class="listitem">
! 152: <div class="sect2" title="Commit only code that you have tested.">
1.12 wiz 153: <div class="titlepage"><div><div><h3 class="title">
154: <a name="tested"></a>Commit only code that you have tested.</h3></div></div></div>
1.1 jschauma 155:
156: <p>
157: Make sure that your code actually works as expected, by
158: compiling and running the code that is affected by your change
159: with your system's tools. If you changed a man page, make sure
160: that groff/nroff creates the formatted man page you expect.
161: </p>
162: <p>
163: For normal commits (to the trunk), test that your code works
1.31 kano 164: on -current. Prior to requesting a pull-up to a branch, test
1.1 jschauma 165: the very changes you will request from releng on the respective
166: release branch.
167: </p>
1.45 ! pooka 168: <p>
! 169: Run all relevant tests from
! 170: <code class="filename">/usr/tests</code> or
! 171: ideally the whole test suite. The logs of the automated
! 172: test runs are currently available
! 173: <a class="ulink" href="http://www.gson.org/netbsd/bugs/build/" target="_top">here</a>.
! 174: Long-term regressions (build breakage or failing tests)
! 175: are not acceptable and changes causing such will be backed
! 176: out if the regressions are not addressed.
! 177: </p>
1.1 jschauma 178: </div>
179: </li>
1.45 ! pooka 180: <li class="listitem">
! 181: <div class="sect2" title="Group commits together that are part of the same fix.">
1.12 wiz 182: <div class="titlepage"><div><div><h3 class="title">
183: <a name="group"></a>Group commits together that are part of the same fix.</h3></div></div></div>
1.1 jschauma 184:
185: <p>
186: Rototilling a make variable that affects 50 Makefiles should get
187: one commit for all of them together.
188: </p>
189: </div>
190: </li>
1.45 ! pooka 191: <li class="listitem">
! 192: <div class="sect2" title="Each commit should be a separate patch/fix/addition/etc.">
1.12 wiz 193: <div class="titlepage"><div><div><h3 class="title">
194: <a name="separate"></a>Each commit should be a separate patch/fix/addition/etc.</h3></div></div></div>
1.1 jschauma 195:
196: <p>
197: Don't fix 3 bugs with the same commit and roll that into
198: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
199: makes life infinitely easier for releng to pull up fixes since
200: often not everything applies to a given branch.
201: </p>
202: </div>
203: </li>
1.45 ! pooka 204: <li class="listitem">
! 205: <div class="sect2" title="Do not mix functionality or bug-fix patches with whitespace/layout updates.">
1.12 wiz 206: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 207: <a name="dont-mix"></a>
208: Do not mix functionality or bug-fix patches with
209: whitespace/layout updates.
1.12 wiz 210: </h3></div></div></div>
1.1 jschauma 211:
212: <p>
213: Do those separately (apart from the general requirement that
214: changes be made in such a way that it is easy to discern what
215: each fix did, as described in item 6, there will be pullup
216: issues with largely changed files from trunk->branch when
217: mixing whitespace with functionality fixes).
218: </p>
219: </div>
220: </li>
1.45 ! pooka 221: <li class="listitem">
! 222: <div class="sect2" title="Clearly document your changes in the commit log.">
1.12 wiz 223: <div class="titlepage"><div><div><h3 class="title">
224: <a name="document"></a>Clearly document your changes in the commit log.</h3></div></div></div>
1.1 jschauma 225:
226: <p>
227: Detail to some degree what was changed and why. Doesn't need
228: to be a code review/walkthrough but it should be informative
229: to someone reading the log and looking over the diff in 6
230: months. Again "fixed some stuff" or "cvs-1.10.0" isn't
231: acceptable whereas the following example is:
232: </p>
233: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
234: <h3 class="title"></h3>
235: "Print useful line number on error while executing .for directive."
236: </div>
237: <p>
1.32 heinz 238: If your change fixes a PR, document it with an appropriate
1.45 ! pooka 239: message. Using the template <span class="quote">“<span class="quote">PR category/bug-id</span>”</span> in
1.32 heinz 240: your commit message will also append it to the respective problem
241: report in our bug database:
1.1 jschauma 242: </p>
243: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
244: <h3 class="title"></h3>
245: "Closes PR bin/6666"
246: </div>
247: <p>
248: If your code has been reviewed by someone else, document this:
249: </p>
250: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
251: <h3 class="title"></h3>
252: "Reviewed by <mrg>"
253: </div>
254: <p>
255: (Please note that a good commit log doesn't relieve the need
256: for good documentation in the program itself.)
257: </p>
258: </div>
259: </li>
1.45 ! pooka 260: <li class="listitem">
! 261: <div class="sect2" title="Give proper credit.">
1.12 wiz 262: <div class="titlepage"><div><div><h3 class="title">
263: <a name="credit"></a>Give proper credit.</h3></div></div></div>
1.1 jschauma 264:
265: <p>
266: If you commit code that had been submitted in a PR, give
267: proper credit, like:
268: </p>
269: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
270: <h3 class="title"></h3>
271: "Code submitted in PR lib/393939 by Joe Doe"
272: </div>
273: <p>
274: Since the commit messages will eventually appear on the
275: source-changes mailing list which is also available via web,
276: specifying the e-mail addresses of the PR submitter should
277: generally be avoided.
278: </p>
279: <p>
280: If you took code from an other Open Source Project, give
281: credit, like:
282: </p>
283: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
284: <h3 class="title"></h3>
285: "From FreeBSD"
286: </div>
287: </div>
288: </li>
1.45 ! pooka 289: <li class="listitem">
! 290: <div class="sect2" title="Do not revert other developer's commits.">
1.12 wiz 291: <div class="titlepage"><div><div><h3 class="title">
292: <a name="revert"></a>Do not revert other developer's commits.</h3></div></div></div>
1.1 jschauma 293:
294: <p>
295: If you do not agree with another developer's commit, do not
296: revert it on your own. Contact the other developer and explain
297: to him or her the issues you have with his commit. Ask him
298: or her to backout his changes himself.
299: </p>
300: <p>
301: If no agreement can be reached, contact the Technical
302: Executive Committee <technical-exec@NetBSD.org>, which
303: will serve as mediation authority.
304: </p>
305: </div>
306: </li>
307: </ol></div>
308:
309: </div>
1.34 dsieger 310: </div></div></div>
311: <div class="navfoot"></div>
1.43 mishka 312: <div id="footer"><div id="footerContent"><center>
1.34 dsieger 313: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">
314: Contact</a> |
1.40 kano 315: </span><span class="footcopy"><a href="../about/disclaimer.html">
1.34 dsieger 316: Disclaimer</a> |
1.1 jschauma 317:
1.44 tonnerre 318: <span class="copyright">Copyright © 1994-2010 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
1.34 dsieger 319: Foundation, Inc.</span>
1.43 mishka 320: </center></div></div>
1.1 jschauma 321: </div></body>
322: </html>
CVSweb <webmaster@jp.NetBSD.org>