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

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

CVSweb <webmaster@jp.NetBSD.org>