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-&gt;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 &lt;mrg&gt;"
        !           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 &lt;technical-exec@NetBSD.org&gt;, 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>