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