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