Annotation of htdocs/developers/commit-guidelines.html, revision 1.34

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

CVSweb <webmaster@jp.NetBSD.org>