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