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

1.1       jschauma    1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
                      2: <html xmlns:html="http://www.w3.org/1999/xhtml">
                      3: <head>
                      4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
                      5: <meta name="generator" content="Website XSL Stylesheet V2.3">
1.6       jschauma    6: <link rel="home" href="../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
                      7: <link rel="up" href="../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
                      8: <link rel="previous" href="../developers/manpages.html" title="NetBSD man page style">
1.7       jschauma    9: <link rel="next" href="../gallery/events.html" title="NetBSD Events">
1.6       jschauma   10: <link rel="first" href="../releng/." title="NetBSD Release Engineering">
1.7       jschauma   11: <link rel="last" href="../gallery/sites.html" title="Sites running NetBSD">
1.1       jschauma   12: <link rel="stylesheet" href="/NetBSD.css" type="text/css">
                     13: <title>NetBSD Commit Guidelines</title>
                     14: </head>
                     15: <body class="website" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="webpage">
                     16: <a name="commit-guidelines"></a><h1>NetBSD Commit Guidelines</h1>
                     17: <div class="sect1" lang="en">
                     18: <div class="titlepage">
                     19: <div><div><h2 class="title" style="clear: both">
                     20: <a name="guidelines"></a>
                     21:   The following Commit Guidelines define the Project's standards for making
                     22:   commits to the source tree:
                     23: </h2></div></div>
                     24: <div></div>
                     25: </div>
                     26: 
                     27: 
                     28: 
                     29: <div class="orderedlist"><ol type="1">
                     30: <li>
                     31:     <div class="sect2" lang="en">
                     32: <div class="titlepage">
                     33: <div><div><h3 class="title">
                     34: <a name="know-thy-code"></a>Commit only code you are familiar with.</h3></div></div>
                     35: <div></div>
                     36: </div>
                     37:       
                     38:       <p>
                     39:         If you are not sure if the code you plan to commit is acceptable
                     40:         (e. g. when taking code that was submitted with a problem report),
                     41:        ask a developer who is familiar with that part of the system for
                     42:        review. If you're new to the Project, check with your sponsor.
                     43:       </p>
                     44:     </div>
                     45:    </li>
                     46: <li>
                     47:     <div class="sect2" lang="en">
                     48: <div class="titlepage">
                     49: <div><div><h3 class="title">
                     50: <a name="tainted"></a>Do not commit tainted code to the repository.</h3></div></div>
                     51: <div></div>
                     52: </div>
                     53:       
                     54:       <p>
                     55:        If you commit code that was not written by yourself, double check
                     56:        that the license on that code permits import into the NetBSD source
                     57:        repository, and permits free distribution. Check with the author(s)
                     58:        of the code, make sure that they were the sole author of the code
                     59:        and verify with them that they did not copy any other code.
                     60:       </p>
                     61:     </div>
                     62:    </li>
                     63: <li>
                     64:     <div class="sect2" lang="en">
                     65: <div class="titlepage">
                     66: <div><div><h3 class="title">
                     67: <a name="intrusive"></a>
                     68:        The more intrusive your changes are the higher is the level of
                     69:        required prior approval.
                     70:       </h3></div></div>
                     71: <div></div>
                     72: </div>
                     73:       
                     74:       <div class="itemizedlist"><ul type="disc">
                     75: <li>
                     76:           <p>
                     77:            "Obvious" fixes can be committed without any prior discussion
                     78:            or review. (The definition of "obvious" in the GCC Project is:
                     79:            "could not possibly cause anyone to object." We adopt this
                     80:            definition here)
                     81:          </p>
                     82:        </li>
                     83: <li>
                     84:          <p>
                     85:            All other (i. e. "non-obvious") fixes <span class="emphasis"><em>should</em></span>
                     86:            have a review.
                     87:          </p>
                     88:        </li>
                     89: <li>
                     90:          <p>
                     91:            Implementing (significant) new features requires a prior
                     92:            discussion on an appropriate technical mailing list.
                     93:          </p>
                     94:        </li>
                     95: <li>
                     96:          <p>
                     97:            Changing existing interfaces in libraries or in the kernel
                     98:            requires prior approval by Core.
                     99:          </p>
                    100:        </li>
                    101: </ul></div>
                    102:     </div>
                    103:    </li>
                    104: <li>
                    105:     <div class="sect2" lang="en">
                    106: <div class="titlepage">
                    107: <div><div><h3 class="title">
                    108: <a name="tested"></a>Commit only code that you have tested.</h3></div></div>
                    109: <div></div>
                    110: </div>
                    111:       
                    112:        <p>
                    113:          Make sure that your code actually works as expected, by
                    114:          compiling and running the code that is affected by your change
                    115:          with your system's tools. If you changed a man page, make sure
                    116:          that groff/nroff creates the formatted man page you expect.
                    117:        </p>
                    118:        <p>
                    119:          For normal commits (to the trunk), test that your code works
                    120:          on -current. Prior to reqesting a pull-up to a branch, test
                    121:          the very changes you will request from releng on the respective
                    122:          release branch.
                    123:        </p>
                    124:      </div>
                    125:     </li>
                    126: <li>
                    127:       <div class="sect2" lang="en">
                    128: <div class="titlepage">
                    129: <div><div><h3 class="title">
                    130: <a name="group"></a>Group commits together that are part of the same fix.</h3></div></div>
                    131: <div></div>
                    132: </div>
                    133:        
                    134:        <p>
                    135:          Rototilling a make variable that affects 50 Makefiles should get
                    136:           one commit for all of them together.
                    137:        </p>
                    138:       </div>
                    139:     </li>
                    140: <li>
                    141:       <div class="sect2" lang="en">
                    142: <div class="titlepage">
                    143: <div><div><h3 class="title">
                    144: <a name="separate"></a>Each commit should be a separate patch/fix/addition/etc.</h3></div></div>
                    145: <div></div>
                    146: </div>
                    147:        
                    148:        <p>
                    149:          Don't fix 3 bugs with the same commit and roll that into
                    150:          "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
                    151:          makes life infinitely easier for releng to pull up fixes since
                    152:          often not everything applies to a given branch.
                    153:        </p>
                    154:       </div>
                    155:     </li>
                    156: <li>
                    157:       <div class="sect2" lang="en">
                    158: <div class="titlepage">
                    159: <div><div><h3 class="title">
                    160: <a name="dont-mix"></a>
                    161:          Do not mix functionality or bug-fix patches with
                    162:          whitespace/layout updates.
                    163:        </h3></div></div>
                    164: <div></div>
                    165: </div>
                    166:        
                    167:         <p>
                    168:          Do those separately (apart from the general requirement that
                    169:          changes be made in such a way that it is easy to discern what
                    170:          each fix did, as described in item 6, there will be pullup
                    171:          issues with largely changed files from trunk-&gt;branch when
                    172:          mixing whitespace with functionality fixes).
                    173:        </p>
                    174:       </div>
                    175:     </li>
                    176: <li>
                    177:       <div class="sect2" lang="en">
                    178: <div class="titlepage">
                    179: <div><div><h3 class="title">
                    180: <a name="document"></a>Clearly document your changes in the commit log.</h3></div></div>
                    181: <div></div>
                    182: </div>
                    183:        
                    184:        <p>
                    185:          Detail to some degree what was changed and why. Doesn't need
                    186:          to be a code review/walkthrough but it should be informative
                    187:          to someone reading the log and looking over the diff in 6
                    188:          months. Again "fixed some stuff" or "cvs-1.10.0" isn't
                    189:          acceptable whereas the following example is:
                    190:        </p>
                    191:        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
                    192: <h3 class="title"></h3>
                    193:           "Print useful line number on error while executing .for directive."
                    194:         </div>
                    195:        <p>
                    196:          If your change fixes a PR, document this:
                    197:        </p>
                    198:        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
                    199: <h3 class="title"></h3>
                    200:           "Closes PR bin/6666"
                    201:         </div>
                    202:        <p>
                    203:          If your code has been reviewed by someone else, document this:
                    204:        </p>
                    205:        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
                    206: <h3 class="title"></h3>
                    207:           "Reviewed by &lt;mrg&gt;"
                    208:        </div>
                    209:        <p>
                    210:          (Please note that a good commit log doesn't relieve the need
                    211:          for good documentation in the program itself.)
                    212:        </p>
                    213:       </div>
                    214:     </li>
                    215: <li>
                    216:       <div class="sect2" lang="en">
                    217: <div class="titlepage">
                    218: <div><div><h3 class="title">
                    219: <a name="credit"></a>Give proper credit.</h3></div></div>
                    220: <div></div>
                    221: </div>
                    222:        
                    223:        <p>
                    224:          If you commit code that had been submitted in a PR, give
                    225:          proper credit, like:
                    226:        </p>
                    227:        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
                    228: <h3 class="title"></h3>
                    229:            "Code submitted in PR lib/393939 by Joe Doe"
                    230:        </div>
                    231:        <p>
                    232:          Since the commit messages will eventually appear on the
                    233:          source-changes mailing list which is also available via web,
                    234:          specifying the e-mail addresses of the PR submitter should
                    235:          generally be avoided.
                    236:        </p>
                    237:        <p>
                    238:          If you took code from an other Open Source Project, give
                    239:          credit, like:
                    240:        </p>
                    241:        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
                    242: <h3 class="title"></h3>
                    243:           "From FreeBSD"
                    244:        </div>
                    245:       </div>
                    246:     </li>
                    247: <li>
                    248:       <div class="sect2" lang="en">
                    249: <div class="titlepage">
                    250: <div><div><h3 class="title">
                    251: <a name="revert"></a>Do not revert other developer's commits.</h3></div></div>
                    252: <div></div>
                    253: </div>
                    254:        
                    255:        <p>
                    256:          If you do not agree with another developer's commit, do not
                    257:          revert it on your own. Contact the other developer and explain
                    258:          to him or her the issues you have with his commit. Ask him
                    259:          or her to backout his changes himself.
                    260:        </p>
                    261:        <p>
                    262:          If no agreement can be reached, contact the Technical
                    263:          Executive Committee &lt;technical-exec@NetBSD.org&gt;, which
                    264:          will serve as mediation authority.
                    265:        </p>
                    266:       </div>
                    267:   </li>
                    268: </ol></div>
                    269: 
                    270: </div>
                    271: <div class="navfoot">
                    272: <hr>
                    273: <table border="0" summary="Footer navigation"><tr>
1.6       jschauma  274: <td class="foothome"><span class="foothome"><a href="../."><img src="/images/NetBSD-flag.png" alt="" border="0" width="90" height="90"></a></span></td>
1.1       jschauma  275: <td class="foothome">
1.6       jschauma  276: <span class="foothome"><a href="../.">Home page</a></span><br>
1.1       jschauma  277: </td>
                    278: </tr></table>
                    279: <hr>
                    280: </div>
                    281: <p></p>
                    282: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">(contact us)</a></span>
                    283: 
                    284:    
1.2       jschauma  285:   <span class="foottag">$NetBSD: commit-guidelines.xml,v 1.1 2004/04/04 21:30:56 jschauma Exp $</span><br><span class="footcopy"><a href="/Misc/disclaimer.html"><span class="copyright">Copyright © 1994-2004 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.</a></span>
1.1       jschauma  286: </div></body>
                    287: </html>

CVSweb <webmaster@jp.NetBSD.org>