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