Annotation of htdocs/developers/commit-guidelines.html, revision 1.10
1.1 jschauma 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2: <html xmlns:html="http://www.w3.org/1999/xhtml">
3: <head>
4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5: <meta name="generator" content="Website XSL Stylesheet V2.3">
1.6 jschauma 6: <link rel="home" href="../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
7: <link rel="up" href="../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
8: <link rel="previous" href="../developers/manpages.html" title="NetBSD man page style">
1.9 symka 9: <link rel="next" href="../errors/index.html" title="404 Not Found">
1.6 jschauma 10: <link rel="first" href="../releng/." title="NetBSD Release Engineering">
1.10 ! jschauma 11: <link rel="last" href="../gallery/software.html" title="Commercial Software">
1.1 jschauma 12: <link rel="stylesheet" href="/NetBSD.css" type="text/css">
13: <title>NetBSD Commit Guidelines</title>
14: </head>
15: <body class="website" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="webpage">
16: <a name="commit-guidelines"></a><h1>NetBSD Commit Guidelines</h1>
17: <div class="sect1" lang="en">
18: <div class="titlepage">
19: <div><div><h2 class="title" style="clear: both">
20: <a name="guidelines"></a>
21: The following Commit Guidelines define the Project's standards for making
22: commits to the source tree:
23: </h2></div></div>
24: <div></div>
25: </div>
26:
27:
28:
29: <div class="orderedlist"><ol type="1">
30: <li>
31: <div class="sect2" lang="en">
32: <div class="titlepage">
33: <div><div><h3 class="title">
34: <a name="know-thy-code"></a>Commit only code you are familiar with.</h3></div></div>
35: <div></div>
36: </div>
37:
38: <p>
39: If you are not sure if the code you plan to commit is acceptable
40: (e. g. when taking code that was submitted with a problem report),
41: ask a developer who is familiar with that part of the system for
42: review. If you're new to the Project, check with your sponsor.
43: </p>
44: </div>
45: </li>
46: <li>
47: <div class="sect2" lang="en">
48: <div class="titlepage">
49: <div><div><h3 class="title">
50: <a name="tainted"></a>Do not commit tainted code to the repository.</h3></div></div>
51: <div></div>
52: </div>
53:
54: <p>
55: If you commit code that was not written by yourself, double check
56: that the license on that code permits import into the NetBSD source
57: repository, and permits free distribution. Check with the author(s)
58: of the code, make sure that they were the sole author of the code
59: and verify with them that they did not copy any other code.
60: </p>
61: </div>
62: </li>
63: <li>
64: <div class="sect2" lang="en">
65: <div class="titlepage">
66: <div><div><h3 class="title">
67: <a name="intrusive"></a>
68: The more intrusive your changes are the higher is the level of
69: required prior approval.
70: </h3></div></div>
71: <div></div>
72: </div>
73:
74: <div class="itemizedlist"><ul type="disc">
75: <li>
76: <p>
77: "Obvious" fixes can be committed without any prior discussion
78: or review. (The definition of "obvious" in the GCC Project is:
79: "could not possibly cause anyone to object." We adopt this
80: definition here)
81: </p>
82: </li>
83: <li>
84: <p>
85: All other (i. e. "non-obvious") fixes <span class="emphasis"><em>should</em></span>
86: have a review.
87: </p>
88: </li>
89: <li>
90: <p>
91: Implementing (significant) new features requires a prior
92: discussion on an appropriate technical mailing list.
93: </p>
94: </li>
95: <li>
96: <p>
97: Changing existing interfaces in libraries or in the kernel
98: requires prior approval by Core.
99: </p>
100: </li>
101: </ul></div>
102: </div>
103: </li>
104: <li>
105: <div class="sect2" lang="en">
106: <div class="titlepage">
107: <div><div><h3 class="title">
108: <a name="tested"></a>Commit only code that you have tested.</h3></div></div>
109: <div></div>
110: </div>
111:
112: <p>
113: Make sure that your code actually works as expected, by
114: compiling and running the code that is affected by your change
115: with your system's tools. If you changed a man page, make sure
116: that groff/nroff creates the formatted man page you expect.
117: </p>
118: <p>
119: For normal commits (to the trunk), test that your code works
120: on -current. Prior to reqesting a pull-up to a branch, test
121: the very changes you will request from releng on the respective
122: release branch.
123: </p>
124: </div>
125: </li>
126: <li>
127: <div class="sect2" lang="en">
128: <div class="titlepage">
129: <div><div><h3 class="title">
130: <a name="group"></a>Group commits together that are part of the same fix.</h3></div></div>
131: <div></div>
132: </div>
133:
134: <p>
135: Rototilling a make variable that affects 50 Makefiles should get
136: one commit for all of them together.
137: </p>
138: </div>
139: </li>
140: <li>
141: <div class="sect2" lang="en">
142: <div class="titlepage">
143: <div><div><h3 class="title">
144: <a name="separate"></a>Each commit should be a separate patch/fix/addition/etc.</h3></div></div>
145: <div></div>
146: </div>
147:
148: <p>
149: Don't fix 3 bugs with the same commit and roll that into
150: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
151: makes life infinitely easier for releng to pull up fixes since
152: often not everything applies to a given branch.
153: </p>
154: </div>
155: </li>
156: <li>
157: <div class="sect2" lang="en">
158: <div class="titlepage">
159: <div><div><h3 class="title">
160: <a name="dont-mix"></a>
161: Do not mix functionality or bug-fix patches with
162: whitespace/layout updates.
163: </h3></div></div>
164: <div></div>
165: </div>
166:
167: <p>
168: Do those separately (apart from the general requirement that
169: changes be made in such a way that it is easy to discern what
170: each fix did, as described in item 6, there will be pullup
171: issues with largely changed files from trunk->branch when
172: mixing whitespace with functionality fixes).
173: </p>
174: </div>
175: </li>
176: <li>
177: <div class="sect2" lang="en">
178: <div class="titlepage">
179: <div><div><h3 class="title">
180: <a name="document"></a>Clearly document your changes in the commit log.</h3></div></div>
181: <div></div>
182: </div>
183:
184: <p>
185: Detail to some degree what was changed and why. Doesn't need
186: to be a code review/walkthrough but it should be informative
187: to someone reading the log and looking over the diff in 6
188: months. Again "fixed some stuff" or "cvs-1.10.0" isn't
189: acceptable whereas the following example is:
190: </p>
191: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
192: <h3 class="title"></h3>
193: "Print useful line number on error while executing .for directive."
194: </div>
195: <p>
196: If your change fixes a PR, document this:
197: </p>
198: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
199: <h3 class="title"></h3>
200: "Closes PR bin/6666"
201: </div>
202: <p>
203: If your code has been reviewed by someone else, document this:
204: </p>
205: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
206: <h3 class="title"></h3>
207: "Reviewed by <mrg>"
208: </div>
209: <p>
210: (Please note that a good commit log doesn't relieve the need
211: for good documentation in the program itself.)
212: </p>
213: </div>
214: </li>
215: <li>
216: <div class="sect2" lang="en">
217: <div class="titlepage">
218: <div><div><h3 class="title">
219: <a name="credit"></a>Give proper credit.</h3></div></div>
220: <div></div>
221: </div>
222:
223: <p>
224: If you commit code that had been submitted in a PR, give
225: proper credit, like:
226: </p>
227: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
228: <h3 class="title"></h3>
229: "Code submitted in PR lib/393939 by Joe Doe"
230: </div>
231: <p>
232: Since the commit messages will eventually appear on the
233: source-changes mailing list which is also available via web,
234: specifying the e-mail addresses of the PR submitter should
235: generally be avoided.
236: </p>
237: <p>
238: If you took code from an other Open Source Project, give
239: credit, like:
240: </p>
241: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
242: <h3 class="title"></h3>
243: "From FreeBSD"
244: </div>
245: </div>
246: </li>
247: <li>
248: <div class="sect2" lang="en">
249: <div class="titlepage">
250: <div><div><h3 class="title">
251: <a name="revert"></a>Do not revert other developer's commits.</h3></div></div>
252: <div></div>
253: </div>
254:
255: <p>
256: If you do not agree with another developer's commit, do not
257: revert it on your own. Contact the other developer and explain
258: to him or her the issues you have with his commit. Ask him
259: or her to backout his changes himself.
260: </p>
261: <p>
262: If no agreement can be reached, contact the Technical
263: Executive Committee <technical-exec@NetBSD.org>, which
264: will serve as mediation authority.
265: </p>
266: </div>
267: </li>
268: </ol></div>
269:
270: </div>
271: <div class="navfoot">
272: <hr>
273: <table border="0" summary="Footer navigation"><tr>
1.6 jschauma 274: <td class="foothome"><span class="foothome"><a href="../."><img src="/images/NetBSD-flag.png" alt="" border="0" width="90" height="90"></a></span></td>
1.1 jschauma 275: <td class="foothome">
1.6 jschauma 276: <span class="foothome"><a href="../.">Home page</a></span><br>
1.1 jschauma 277: </td>
278: </tr></table>
279: <hr>
280: </div>
281: <p></p>
282: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">(contact us)</a></span>
283:
284:
1.2 jschauma 285: <span class="foottag">$NetBSD: commit-guidelines.xml,v 1.1 2004/04/04 21:30:56 jschauma Exp $</span><br><span class="footcopy"><a href="/Misc/disclaimer.html"><span class="copyright">Copyright © 1994-2004 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.</a></span>
1.1 jschauma 286: </div></body>
287: </html>
CVSweb <webmaster@jp.NetBSD.org>