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

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

CVSweb <webmaster@jp.NetBSD.org>