Annotation of htdocs/developers/commit-guidelines.html, revision 1.39
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.34 dsieger 13: <link rel="stylesheet" href="/global.css" type="text/css">
1.1 jschauma 14: <title>NetBSD Commit Guidelines</title>
15: </head>
1.27 heinz 16: <body class="website"><div class="webpage">
1.34 dsieger 17: <a name="developers-commit-guidelines"></a><div id="top"><a href="#mainContent" class="doNotDisplay doNotPrint">Skip to main content.</a></div>
18: <div id="header">
19: <div class="topNavigation">
1.37 dsieger 20: <span>» </span><a href="../docs/guide/en/">
21: The Guide</a> |
1.34 dsieger 22: <a href="http://man.NetBSD.org/">Manual pages</a> |
1.39 ! kano 23: <a href="../mailinglists/">
1.37 dsieger 24: Mailing lists</a> and
1.34 dsieger 25: <a href="http://mail-index.NetBSD.org/">Archives</a> |
26: <a href="http://cvsweb.NetBSD.org/">CVS repository</a> |
1.37 dsieger 27: <a href="http://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd">Report</a>
28: or
1.38 dsieger 29: <a href="http://www.NetBSD.org/support/query-pr.html">query</a> a bug |
1.37 dsieger 30: <a href="../docs/software/packages.html">
31: Software Packages
32: </a>
1.34 dsieger 33: </div>
34: <div class="centralHeader">
1.37 dsieger 35: <a href="../"><img alt="[NetBSD Logo]" width="506" height="90" src="../images/NetBSD-headerlogo.png"></a><div class="headerTools"><div id="headerSearch"><form method="get" action="http://www.google.com/custom">
1.35 dsieger 36: <input class="whiteOnBlack" type="text" name="q" onfocus="if(this.value==this.defaultValue ) this.value='';" size="12" maxlength="255" value="Search"><input type="hidden" name="cof" value="L:http://www.NetBSD.org/images/NetBSD-smaller.png;LH:200;LW:200;AH:center;AWFID:4f6b0499f0f58d2c;"><input type="hidden" name="domains" value="NetBSD.org"><input type="hidden" name="sitesearch" value="www.NetBSD.org"><input type="submit" value="Search">
1.34 dsieger 37: </form></div></div>
38: </div>
39: <div class="navBar">
1.37 dsieger 40: <span class="doNotDisplay">
41: Navigation:
42: </span><a href="../">
43: Home</a> |
44: <a href="../about/">
45: About</a> |
46: <a href="../releases/">
47: Download</a> |
48: <a href="../docs/">
49: Documentation</a> |
50: <a href="../support/">
51: Support</a> |
52: <a href="../community/">
53: Community</a> |
54: <a href="../ports/">
55: Ports</a>
1.34 dsieger 56: </div>
57: </div>
58: <div id="content"><div class="fullWidth"><div class="rowOfBoxes">
59: <h1>NetBSD Commit Guidelines</h1>
1.1 jschauma 60: <div class="sect1" lang="en">
1.12 wiz 61: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.1 jschauma 62: <a name="guidelines"></a>
63: The following Commit Guidelines define the Project's standards for making
64: commits to the source tree:
1.12 wiz 65: </h2></div></div></div>
1.1 jschauma 66:
67:
68:
69: <div class="orderedlist"><ol type="1">
70: <li>
71: <div class="sect2" lang="en">
1.12 wiz 72: <div class="titlepage"><div><div><h3 class="title">
73: <a name="know-thy-code"></a>Commit only code you are familiar with.</h3></div></div></div>
1.1 jschauma 74:
75: <p>
76: If you are not sure if the code you plan to commit is acceptable
77: (e. g. when taking code that was submitted with a problem report),
78: ask a developer who is familiar with that part of the system for
79: review. If you're new to the Project, check with your sponsor.
80: </p>
81: </div>
82: </li>
83: <li>
84: <div class="sect2" lang="en">
1.12 wiz 85: <div class="titlepage"><div><div><h3 class="title">
86: <a name="tainted"></a>Do not commit tainted code to the repository.</h3></div></div></div>
1.1 jschauma 87:
88: <p>
89: If you commit code that was not written by yourself, double check
90: that the license on that code permits import into the NetBSD source
91: repository, and permits free distribution. Check with the author(s)
92: of the code, make sure that they were the sole author of the code
93: and verify with them that they did not copy any other code.
94: </p>
95: </div>
96: </li>
97: <li>
98: <div class="sect2" lang="en">
1.12 wiz 99: <div class="titlepage"><div><div><h3 class="title">
1.29 jschauma 100: <a name="repository"></a>Do not commit code from foreign trees.</h3></div></div></div>
101:
102: <p>
103: Do not commit code from a tree checked out from anywhere but from
104: cvs.NetBSD.org. Note that all developers have access to the private
105: <a href="restricted.html#rsync" target="_top">rsync-over-ssh service on
106: cvs.NetBSD.org</a>.
107: </p>
108: </div>
109: </li>
110: <li>
111: <div class="sect2" lang="en">
112: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 113: <a name="intrusive"></a>
114: The more intrusive your changes are the higher is the level of
115: required prior approval.
1.12 wiz 116: </h3></div></div></div>
1.1 jschauma 117:
118: <div class="itemizedlist"><ul type="disc">
119: <li>
120: <p>
121: "Obvious" fixes can be committed without any prior discussion
122: or review. (The definition of "obvious" in the GCC Project is:
123: "could not possibly cause anyone to object." We adopt this
124: definition here)
125: </p>
126: </li>
127: <li>
128: <p>
129: All other (i. e. "non-obvious") fixes <span class="emphasis"><em>should</em></span>
130: have a review.
131: </p>
132: </li>
133: <li>
134: <p>
135: Implementing (significant) new features requires a prior
136: discussion on an appropriate technical mailing list.
137: </p>
138: </li>
139: <li>
140: <p>
141: Changing existing interfaces in libraries or in the kernel
142: requires prior approval by Core.
143: </p>
144: </li>
145: </ul></div>
146: </div>
147: </li>
148: <li>
149: <div class="sect2" lang="en">
1.12 wiz 150: <div class="titlepage"><div><div><h3 class="title">
151: <a name="tested"></a>Commit only code that you have tested.</h3></div></div></div>
1.1 jschauma 152:
153: <p>
154: Make sure that your code actually works as expected, by
155: compiling and running the code that is affected by your change
156: with your system's tools. If you changed a man page, make sure
157: that groff/nroff creates the formatted man page you expect.
158: </p>
159: <p>
160: For normal commits (to the trunk), test that your code works
1.31 kano 161: on -current. Prior to requesting a pull-up to a branch, test
1.1 jschauma 162: the very changes you will request from releng on the respective
163: release branch.
164: </p>
165: </div>
166: </li>
167: <li>
168: <div class="sect2" lang="en">
1.12 wiz 169: <div class="titlepage"><div><div><h3 class="title">
170: <a name="group"></a>Group commits together that are part of the same fix.</h3></div></div></div>
1.1 jschauma 171:
172: <p>
173: Rototilling a make variable that affects 50 Makefiles should get
174: one commit for all of them together.
175: </p>
176: </div>
177: </li>
178: <li>
179: <div class="sect2" lang="en">
1.12 wiz 180: <div class="titlepage"><div><div><h3 class="title">
181: <a name="separate"></a>Each commit should be a separate patch/fix/addition/etc.</h3></div></div></div>
1.1 jschauma 182:
183: <p>
184: Don't fix 3 bugs with the same commit and roll that into
185: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
186: makes life infinitely easier for releng to pull up fixes since
187: often not everything applies to a given branch.
188: </p>
189: </div>
190: </li>
191: <li>
192: <div class="sect2" lang="en">
1.12 wiz 193: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 194: <a name="dont-mix"></a>
195: Do not mix functionality or bug-fix patches with
196: whitespace/layout updates.
1.12 wiz 197: </h3></div></div></div>
1.1 jschauma 198:
199: <p>
200: Do those separately (apart from the general requirement that
201: changes be made in such a way that it is easy to discern what
202: each fix did, as described in item 6, there will be pullup
203: issues with largely changed files from trunk->branch when
204: mixing whitespace with functionality fixes).
205: </p>
206: </div>
207: </li>
208: <li>
209: <div class="sect2" lang="en">
1.12 wiz 210: <div class="titlepage"><div><div><h3 class="title">
211: <a name="document"></a>Clearly document your changes in the commit log.</h3></div></div></div>
1.1 jschauma 212:
213: <p>
214: Detail to some degree what was changed and why. Doesn't need
215: to be a code review/walkthrough but it should be informative
216: to someone reading the log and looking over the diff in 6
217: months. Again "fixed some stuff" or "cvs-1.10.0" isn't
218: acceptable whereas the following example is:
219: </p>
220: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
221: <h3 class="title"></h3>
222: "Print useful line number on error while executing .for directive."
223: </div>
224: <p>
1.32 heinz 225: If your change fixes a PR, document it with an appropriate
226: message. Using the template “<span class="quote">PR category/bug-id</span>” in
227: your commit message will also append it to the respective problem
228: report in our bug database:
1.1 jschauma 229: </p>
230: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
231: <h3 class="title"></h3>
232: "Closes PR bin/6666"
233: </div>
234: <p>
235: If your code has been reviewed by someone else, document this:
236: </p>
237: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
238: <h3 class="title"></h3>
239: "Reviewed by <mrg>"
240: </div>
241: <p>
242: (Please note that a good commit log doesn't relieve the need
243: for good documentation in the program itself.)
244: </p>
245: </div>
246: </li>
247: <li>
248: <div class="sect2" lang="en">
1.12 wiz 249: <div class="titlepage"><div><div><h3 class="title">
250: <a name="credit"></a>Give proper credit.</h3></div></div></div>
1.1 jschauma 251:
252: <p>
253: If you commit code that had been submitted in a PR, give
254: proper credit, like:
255: </p>
256: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
257: <h3 class="title"></h3>
258: "Code submitted in PR lib/393939 by Joe Doe"
259: </div>
260: <p>
261: Since the commit messages will eventually appear on the
262: source-changes mailing list which is also available via web,
263: specifying the e-mail addresses of the PR submitter should
264: generally be avoided.
265: </p>
266: <p>
267: If you took code from an other Open Source Project, give
268: credit, like:
269: </p>
270: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
271: <h3 class="title"></h3>
272: "From FreeBSD"
273: </div>
274: </div>
275: </li>
276: <li>
277: <div class="sect2" lang="en">
1.12 wiz 278: <div class="titlepage"><div><div><h3 class="title">
279: <a name="revert"></a>Do not revert other developer's commits.</h3></div></div></div>
1.1 jschauma 280:
281: <p>
282: If you do not agree with another developer's commit, do not
283: revert it on your own. Contact the other developer and explain
284: to him or her the issues you have with his commit. Ask him
285: or her to backout his changes himself.
286: </p>
287: <p>
288: If no agreement can be reached, contact the Technical
289: Executive Committee <technical-exec@NetBSD.org>, which
290: will serve as mediation authority.
291: </p>
292: </div>
293: </li>
294: </ol></div>
295:
296: </div>
1.34 dsieger 297: </div></div></div>
298: <div class="navfoot"></div>
299: <div id="footer"><center>
300: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">
301: Contact</a> |
302: </span><span class="footcopy"><a href="/about/disclaimer.html">
303: Disclaimer</a> |
1.1 jschauma 304:
1.34 dsieger 305: <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
306: Foundation, Inc.</span>
307: </center></div>
1.1 jschauma 308: </div></body>
309: </html>
CVSweb <webmaster@jp.NetBSD.org>