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

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

CVSweb <webmaster@jp.NetBSD.org>