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

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

CVSweb <webmaster@jp.NetBSD.org>