Annotation of htdocs/developers/commit-guidelines.html, revision 1.48
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.41 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.40 kano 29: <a href="../support/query-pr.html">
30: query</a> a bug |
1.37 dsieger 31: <a href="../docs/software/packages.html">
32: Software Packages
33: </a>
1.34 dsieger 34: </div>
35: <div class="centralHeader">
1.48 ! spz 36: <a href="../"><img alt="[NetBSD Logo]" width="506" height="90" src="../images/NetBSD-headerlogo.png"></a><div class="headerTools"><div id="headerSearch">
! 37: <div id="header-cse-search-form" style="width: 24%;">Google custom search</div>
! 38: <script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript">
! 39: google.load('search', '1', {language : 'en'});
! 40: google.setOnLoadCallback(function() {
! 41: var header_customSearchControl = new google.search.CustomSearchControl('006277936787196004968:mbdhrauy1wm');
! 42: header_customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET);
! 43: var header_options = new google.search.DrawOptions();
! 44: header_options.enableSearchboxOnly("http://google.com/cse?cx=006277936787196004968:mbdhrauy1wm");
! 45: header_customSearchControl.draw('header-cse-search-form', header_options);
! 46: }, true);
! 47: </script><link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css">
! 48: </div></div>
1.34 dsieger 49: </div>
50: <div class="navBar">
1.37 dsieger 51: <span class="doNotDisplay">
52: Navigation:
53: </span><a href="../">
54: Home</a> |
55: <a href="../about/">
56: About</a> |
1.42 hubertf 57: <a href="../gallery/">
58: Gallery</a> |
1.37 dsieger 59: <a href="../releases/">
60: Download</a> |
61: <a href="../docs/">
62: Documentation</a> |
63: <a href="../support/">
64: Support</a> |
65: <a href="../community/">
66: Community</a> |
67: <a href="../ports/">
68: Ports</a>
1.34 dsieger 69: </div>
70: </div>
71: <div id="content"><div class="fullWidth"><div class="rowOfBoxes">
72: <h1>NetBSD Commit Guidelines</h1>
1.48 ! spz 73: <div class="sect1" title="The following Commit Guidelines define the Project's standards for making commits to the source tree:">
1.12 wiz 74: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.1 jschauma 75: <a name="guidelines"></a>
76: The following Commit Guidelines define the Project's standards for making
77: commits to the source tree:
1.12 wiz 78: </h2></div></div></div>
1.1 jschauma 79:
80:
81:
1.48 ! spz 82: <div class="orderedlist"><ol class="orderedlist" type="1">
! 83: <li class="listitem">
! 84: <div class="sect2" title="Commit only code you are familiar with.">
1.12 wiz 85: <div class="titlepage"><div><div><h3 class="title">
86: <a name="know-thy-code"></a>Commit only code you are familiar with.</h3></div></div></div>
1.1 jschauma 87:
88: <p>
89: If you are not sure if the code you plan to commit is acceptable
90: (e. g. when taking code that was submitted with a problem report),
91: ask a developer who is familiar with that part of the system for
92: review. If you're new to the Project, check with your sponsor.
93: </p>
94: </div>
95: </li>
1.48 ! spz 96: <li class="listitem">
! 97: <div class="sect2" title="Do not commit tainted code to the repository.">
1.12 wiz 98: <div class="titlepage"><div><div><h3 class="title">
99: <a name="tainted"></a>Do not commit tainted code to the repository.</h3></div></div></div>
1.1 jschauma 100:
101: <p>
102: If you commit code that was not written by yourself, double check
103: that the license on that code permits import into the NetBSD source
104: repository, and permits free distribution. Check with the author(s)
105: of the code, make sure that they were the sole author of the code
106: and verify with them that they did not copy any other code.
107: </p>
108: </div>
109: </li>
1.48 ! spz 110: <li class="listitem">
! 111: <div class="sect2" title="Do not commit code from foreign trees.">
1.12 wiz 112: <div class="titlepage"><div><div><h3 class="title">
1.29 jschauma 113: <a name="repository"></a>Do not commit code from foreign trees.</h3></div></div></div>
114:
115: <p>
116: Do not commit code from a tree checked out from anywhere but from
117: cvs.NetBSD.org. Note that all developers have access to the private
1.41 dsieger 118: <a class="ulink" href="restricted.html#rsync" target="_top">rsync-over-ssh service on
1.29 jschauma 119: cvs.NetBSD.org</a>.
120: </p>
121: </div>
122: </li>
1.48 ! spz 123: <li class="listitem">
! 124: <div class="sect2" title="The more intrusive your changes are the higher is the level of required prior approval.">
1.29 jschauma 125: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 126: <a name="intrusive"></a>
127: The more intrusive your changes are the higher is the level of
128: required prior approval.
1.12 wiz 129: </h3></div></div></div>
1.1 jschauma 130:
1.48 ! spz 131: <div class="itemizedlist"><ul class="itemizedlist" type="disc">
! 132: <li class="listitem">
1.1 jschauma 133: <p>
134: "Obvious" fixes can be committed without any prior discussion
135: or review. (The definition of "obvious" in the GCC Project is:
136: "could not possibly cause anyone to object." We adopt this
137: definition here)
138: </p>
139: </li>
1.48 ! spz 140: <li class="listitem">
1.1 jschauma 141: <p>
142: All other (i. e. "non-obvious") fixes <span class="emphasis"><em>should</em></span>
143: have a review.
144: </p>
145: </li>
1.48 ! spz 146: <li class="listitem">
1.1 jschauma 147: <p>
148: Implementing (significant) new features requires a prior
149: discussion on an appropriate technical mailing list.
150: </p>
151: </li>
1.48 ! spz 152: <li class="listitem">
1.1 jschauma 153: <p>
1.46 pooka 154: Adding a completely new package (e.g. openldap) requires
155: prior discussion on a mailing list <span class="emphasis"><em>and</em></span>
156: approval from core.
1.1 jschauma 157: </p>
158: </li>
159: </ul></div>
160: </div>
161: </li>
1.48 ! spz 162: <li class="listitem">
! 163: <div class="sect2" title="Commit only code that you have tested.">
1.12 wiz 164: <div class="titlepage"><div><div><h3 class="title">
165: <a name="tested"></a>Commit only code that you have tested.</h3></div></div></div>
1.1 jschauma 166:
167: <p>
168: Make sure that your code actually works as expected, by
169: compiling and running the code that is affected by your change
170: with your system's tools. If you changed a man page, make sure
171: that groff/nroff creates the formatted man page you expect.
172: </p>
173: <p>
174: For normal commits (to the trunk), test that your code works
1.31 kano 175: on -current. Prior to requesting a pull-up to a branch, test
1.1 jschauma 176: the very changes you will request from releng on the respective
177: release branch.
178: </p>
1.45 pooka 179: <p>
180: Run all relevant tests from
181: <code class="filename">/usr/tests</code> or
182: ideally the whole test suite. The logs of the automated
183: test runs are currently available
184: <a class="ulink" href="http://www.gson.org/netbsd/bugs/build/" target="_top">here</a>.
185: Long-term regressions (build breakage or failing tests)
186: are not acceptable and changes causing such will be backed
187: out if the regressions are not addressed.
188: </p>
1.1 jschauma 189: </div>
190: </li>
1.48 ! spz 191: <li class="listitem">
! 192: <div class="sect2" title="Group commits together that are part of the same fix.">
1.12 wiz 193: <div class="titlepage"><div><div><h3 class="title">
194: <a name="group"></a>Group commits together that are part of the same fix.</h3></div></div></div>
1.1 jschauma 195:
196: <p>
197: Rototilling a make variable that affects 50 Makefiles should get
198: one commit for all of them together.
199: </p>
200: </div>
201: </li>
1.48 ! spz 202: <li class="listitem">
! 203: <div class="sect2" title="Each commit should be a separate patch/fix/addition/etc.">
1.12 wiz 204: <div class="titlepage"><div><div><h3 class="title">
205: <a name="separate"></a>Each commit should be a separate patch/fix/addition/etc.</h3></div></div></div>
1.1 jschauma 206:
207: <p>
208: Don't fix 3 bugs with the same commit and roll that into
209: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
210: makes life infinitely easier for releng to pull up fixes since
211: often not everything applies to a given branch.
212: </p>
213: </div>
214: </li>
1.48 ! spz 215: <li class="listitem">
! 216: <div class="sect2" title="Do not mix functionality or bug-fix patches with whitespace/layout updates.">
1.12 wiz 217: <div class="titlepage"><div><div><h3 class="title">
1.1 jschauma 218: <a name="dont-mix"></a>
219: Do not mix functionality or bug-fix patches with
220: whitespace/layout updates.
1.12 wiz 221: </h3></div></div></div>
1.1 jschauma 222:
223: <p>
224: Do those separately (apart from the general requirement that
225: changes be made in such a way that it is easy to discern what
226: each fix did, as described in item 6, there will be pullup
227: issues with largely changed files from trunk->branch when
228: mixing whitespace with functionality fixes).
229: </p>
230: </div>
231: </li>
1.48 ! spz 232: <li class="listitem">
! 233: <div class="sect2" title="Clearly document the reasons for your changes in the commit log.">
1.12 wiz 234: <div class="titlepage"><div><div><h3 class="title">
1.46 pooka 235: <a name="document"></a>Clearly document the reasons for your changes in
236: the commit log.</h3></div></div></div>
1.1 jschauma 237:
238: <p>
1.46 pooka 239: Detail to some degree what was changed and why. This
240: doesn't need to be a code review/walkthrough but it should
241: be informative to someone reading the log and looking
242: over the diff in 6 months. The focus should be on "why"
243: since the target audience reading the logs can usually
244: figure out "what" from looking the diffs. As an exercise,
245: consider the difference of usefulness between "set i to
246: 1" and "initialize iterator correctly to fix a rarely
247: triggering bug in memory handling".
248: </p>
249:
250: <p>
251: Also, "fixed some stuff" or "cvs-1.10.0" isn't informative
252: whereas the following example is:
1.1 jschauma 253: </p>
254: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
255: <h3 class="title"></h3>
256: "Print useful line number on error while executing .for directive."
257: </div>
258: <p>
1.32 heinz 259: If your change fixes a PR, document it with an appropriate
1.48 ! spz 260: message. Using the template <span class="quote">“<span class="quote">PR category/bug-id</span>”</span> in
1.32 heinz 261: your commit message will also append it to the respective problem
262: report in our bug database:
1.1 jschauma 263: </p>
264: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
265: <h3 class="title"></h3>
266: "Closes PR bin/6666"
267: </div>
268: <p>
269: If your code has been reviewed by someone else, document this:
270: </p>
271: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
272: <h3 class="title"></h3>
273: "Reviewed by <mrg>"
274: </div>
275: <p>
276: (Please note that a good commit log doesn't relieve the need
277: for good documentation in the program itself.)
278: </p>
279: </div>
280: </li>
1.48 ! spz 281: <li class="listitem">
! 282: <div class="sect2" title="Give proper credit.">
1.12 wiz 283: <div class="titlepage"><div><div><h3 class="title">
284: <a name="credit"></a>Give proper credit.</h3></div></div></div>
1.1 jschauma 285:
286: <p>
287: If you commit code that had been submitted in a PR, give
288: proper credit, like:
289: </p>
290: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
291: <h3 class="title"></h3>
292: "Code submitted in PR lib/393939 by Joe Doe"
293: </div>
294: <p>
295: Since the commit messages will eventually appear on the
296: source-changes mailing list which is also available via web,
297: specifying the e-mail addresses of the PR submitter should
298: generally be avoided.
299: </p>
300: <p>
301: If you took code from an other Open Source Project, give
302: credit, like:
303: </p>
304: <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
305: <h3 class="title"></h3>
306: "From FreeBSD"
307: </div>
308: </div>
309: </li>
1.48 ! spz 310: <li class="listitem">
! 311: <div class="sect2" title="Do not revert other developer's commits.">
1.12 wiz 312: <div class="titlepage"><div><div><h3 class="title">
313: <a name="revert"></a>Do not revert other developer's commits.</h3></div></div></div>
1.1 jschauma 314:
315: <p>
316: If you do not agree with another developer's commit, do not
317: revert it on your own. Contact the other developer and explain
1.47 spz 318: to him or her the issues you have with the commit in question.
319: Ask the other developer to back out the changes instead of
320: doing it yourself.
1.1 jschauma 321: </p>
322: <p>
323: If no agreement can be reached, contact the Technical
324: Executive Committee <technical-exec@NetBSD.org>, which
325: will serve as mediation authority.
326: </p>
327: </div>
328: </li>
329: </ol></div>
330:
331: </div>
1.34 dsieger 332: </div></div></div>
333: <div class="navfoot"></div>
1.43 mishka 334: <div id="footer"><div id="footerContent"><center>
1.34 dsieger 335: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">
336: Contact</a> |
1.40 kano 337: </span><span class="footcopy"><a href="../about/disclaimer.html">
1.34 dsieger 338: Disclaimer</a> |
1.1 jschauma 339:
1.48 ! spz 340: <span class="copyright">Copyright © 1994-2011 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
1.34 dsieger 341: Foundation, Inc.</span>
1.43 mishka 342: </center></div></div>
1.1 jschauma 343: </div></body>
344: </html>
CVSweb <webmaster@jp.NetBSD.org>