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

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-&gt;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">&#8220;<span class="quote">PR category/bug-id</span>&#8221;</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 &lt;mrg&gt;"
                    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 &lt;technical-exec@NetBSD.org&gt;, 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.49    ! snj       340:       <span class="copyright">Copyright © 1994-2012 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>