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