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

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

CVSweb <webmaster@jp.NetBSD.org>