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