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