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