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