Annotation of htdocs/developers/commit-guidelines.xml, revision 1.13

1.1       jschauma    1: <?xml version="1.0"?>
                      2: <!DOCTYPE webpage
1.2       hrs         3:   PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
                      4:         "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
1.1       jschauma    5: 
1.3       heinz       6: <webpage id="developers-commit-guidelines">
1.1       jschauma    7: <config param="desc" value="NetBSD Commit Guidelines"/>
1.13    ! riastrad    8: <config param="cvstag" value="$NetBSD: commit-guidelines.xml,v 1.12 2024/05/16 04:02:50 gutteridge Exp $"/>
        !             9: <config param="rcsdate" value="$Date: 2024/05/16 04:02:50 $"/>
1.1       jschauma   10: <head>
                     11: <title>NetBSD Commit Guidelines</title>
                     12: </head>
                     13: 
                     14: <sect1 id="guidelines">
                     15: 
                     16: <title>
                     17:   The following Commit Guidelines define the Project's standards for making
                     18:   commits to the source tree:
                     19: </title>
                     20: 
                     21: <orderedlist>
                     22:   <listitem>
                     23:     <sect2 id="know-thy-code">
                     24:       <title>Commit only code you are familiar with.</title>
                     25:       <para>
                     26:         If you are not sure if the code you plan to commit is acceptable
                     27:         (e. g. when taking code that was submitted with a problem report),
                     28:        ask a developer who is familiar with that part of the system for
                     29:        review. If you're new to the Project, check with your sponsor.
                     30:       </para>
                     31:     </sect2>
                     32:    </listitem>
                     33: 
                     34:    <listitem>
                     35:     <sect2 id="tainted">
                     36:       <title>Do not commit tainted code to the repository.</title>
                     37:       <para>
                     38:        If you commit code that was not written by yourself, double check
                     39:        that the license on that code permits import into the NetBSD source
                     40:        repository, and permits free distribution. Check with the author(s)
                     41:        of the code, make sure that they were the sole author of the code
                     42:        and verify with them that they did not copy any other code.
                     43:       </para>
1.11      riastrad   44:       <para>
                     45:         Code generated by a large language model or similar technology,
1.12      gutterid   46:          such as GitHub/Microsoft's Copilot, OpenAI's ChatGPT,
1.11      riastrad   47:          or Facebook/Meta's Code Llama, is presumed to be tainted
                     48:          code, and must not be committed without prior written approval
                     49:          by core.
                     50:       </para>
1.1       jschauma   51:     </sect2>
                     52:    </listitem>
                     53: 
                     54:    <listitem>
1.4       jschauma   55:     <sect2 id="repository">
                     56:       <title>Do not commit code from foreign trees.</title>
                     57:       <para>
                     58:        Do not commit code from a tree checked out from anywhere but from
                     59:        cvs.NetBSD.org.  Note that all developers have access to the private
                     60:        <ulink url="restricted.html#rsync">rsync-over-ssh service on
                     61:        cvs.NetBSD.org</ulink>.
                     62:       </para>
                     63:     </sect2>
                     64:    </listitem>
                     65: 
                     66:    <listitem>
1.1       jschauma   67:     <sect2 id="intrusive">
                     68:       <title>
                     69:        The more intrusive your changes are the higher is the level of
                     70:        required prior approval.
                     71:       </title>
                     72:       <itemizedlist>
                     73:         <listitem>
                     74:           <para>
                     75:            "Obvious" fixes can be committed without any prior discussion
                     76:            or review. (The definition of "obvious" in the GCC Project is:
                     77:            "could not possibly cause anyone to object." We adopt this
                     78:            definition here)
                     79:          </para>
                     80:        </listitem>
                     81:        <listitem>
                     82:          <para>
                     83:            All other (i. e. "non-obvious") fixes <emphasis>should</emphasis>
                     84:            have a review.
                     85:          </para>
                     86:        </listitem>
                     87:        <listitem>
                     88:          <para>
                     89:            Implementing (significant) new features requires a prior
                     90:            discussion on an appropriate technical mailing list.
                     91:          </para>
                     92:        </listitem>
                     93:        <listitem>
                     94:          <para>
1.8       pooka      95:            Adding a completely new package (e.g. openldap) requires
                     96:            prior discussion on a mailing list <emphasis>and</emphasis>
                     97:            approval from core.
1.1       jschauma   98:          </para>
                     99:        </listitem>
                    100:       </itemizedlist>
                    101:     </sect2>
                    102:    </listitem>
                    103:    <listitem>
                    104:     <sect2 id="tested">
                    105:       <title>Commit only code that you have tested.</title>
                    106:        <para>
                    107:          Make sure that your code actually works as expected, by
                    108:          compiling and running the code that is affected by your change
                    109:          with your system's tools. If you changed a man page, make sure
                    110:          that groff/nroff creates the formatted man page you expect.
                    111:        </para>
                    112:        <para>
                    113:          For normal commits (to the trunk), test that your code works
1.5       kano      114:          on -current. Prior to requesting a pull-up to a branch, test
1.1       jschauma  115:          the very changes you will request from releng on the respective
                    116:          release branch.
                    117:        </para>
1.7       pooka     118:        <para>
                    119:          Run all relevant tests from
                    120:          <filename class="directory">/usr/tests</filename> or
1.13    ! riastrad  121:          ideally the whole test suite.
        !           122:          Check the
        !           123:          <ulink url="//releng.NetBSD.org/cgi-bin/builds.cgi">daily
        !           124:            builds</ulink>
        !           125:          and the
        !           126:          <ulink url="//releng.NetBSD.org/test-results.html">automated
        !           127:            test runs</ulink>.
1.7       pooka     128:          Long-term regressions (build breakage or failing tests)
                    129:          are not acceptable and changes causing such will be backed
                    130:          out if the regressions are not addressed.
                    131:        </para>
1.1       jschauma  132:      </sect2>
                    133:     </listitem>
                    134:     <listitem>
                    135:       <sect2 id="group">
                    136:        <title>Group commits together that are part of the same fix.</title>
                    137:        <para>
                    138:          Rototilling a make variable that affects 50 Makefiles should get
                    139:           one commit for all of them together.
                    140:        </para>
                    141:       </sect2>
                    142:     </listitem>
                    143:     <listitem>
                    144:       <sect2 id="separate">
                    145:        <title>Each commit should be a separate patch/fix/addition/etc.</title>
                    146:        <para>
                    147:          Don't fix 3 bugs with the same commit and roll that into
                    148:          "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
                    149:          makes life infinitely easier for releng to pull up fixes since
                    150:          often not everything applies to a given branch.
                    151:        </para>
                    152:       </sect2>
                    153:     </listitem>
                    154:     <listitem>
                    155:       <sect2 id="dont-mix">
                    156:        <title>
                    157:          Do not mix functionality or bug-fix patches with
                    158:          whitespace/layout updates.
                    159:        </title>
                    160:         <para>
                    161:          Do those separately (apart from the general requirement that
                    162:          changes be made in such a way that it is easy to discern what
                    163:          each fix did, as described in item 6, there will be pullup
                    164:          issues with largely changed files from trunk->branch when
                    165:          mixing whitespace with functionality fixes).
                    166:        </para>
                    167:       </sect2>
                    168:     </listitem>
                    169:     <listitem>
                    170:       <sect2 id="document">
1.8       pooka     171:        <title>Clearly document the reasons for your changes in
                    172:               the commit log.</title>
1.1       jschauma  173:        <para>
1.8       pooka     174:          Detail to some degree what was changed and why.  This
                    175:          doesn't need to be a code review/walkthrough but it should
                    176:          be informative to someone reading the log and looking
                    177:          over the diff in 6 months.  The focus should be on "why"
                    178:          since the target audience reading the logs can usually
                    179:          figure out "what" from looking the diffs.  As an exercise,
                    180:          consider the difference of usefulness between "set i to
                    181:          1" and "initialize iterator correctly to fix a rarely
                    182:          triggering bug in memory handling".
                    183:        </para>
                    184: 
                    185:        <para>
                    186:          Also, "fixed some stuff" or "cvs-1.10.0" isn't informative
                    187:          whereas the following example is:
1.1       jschauma  188:        </para>
                    189:        <note><title/>
                    190:           "Print useful line number on error while executing .for directive."
                    191:         </note>
                    192:        <para>
1.6       heinz     193:          If your change fixes a PR, document it with an appropriate
                    194:          message. Using the template <quote>PR category/bug-id</quote> in
                    195:          your commit message will also append it to the respective problem
                    196:          report in our bug database:
1.1       jschauma  197:        </para>
                    198:        <note><title/>
                    199:           "Closes PR bin/6666"
                    200:         </note>
                    201:        <para>
                    202:          If your code has been reviewed by someone else, document this:
                    203:        </para>
                    204:        <note><title/>
                    205:           "Reviewed by &lt;mrg&gt;"
                    206:        </note>
                    207:        <para>
                    208:          (Please note that a good commit log doesn't relieve the need
                    209:          for good documentation in the program itself.)
                    210:        </para>
                    211:       </sect2>
                    212:     </listitem>
                    213:     <listitem>
                    214:       <sect2 id="credit">
                    215:        <title>Give proper credit.</title>
                    216:        <para>
                    217:          If you commit code that had been submitted in a PR, give
                    218:          proper credit, like:
                    219:        </para>
                    220:        <note><title/>
                    221:            "Code submitted in PR lib/393939 by Joe Doe"
                    222:        </note>
                    223:        <para>
                    224:          Since the commit messages will eventually appear on the
                    225:          source-changes mailing list which is also available via web,
                    226:          specifying the e-mail addresses of the PR submitter should
                    227:          generally be avoided.
                    228:        </para>
                    229:        <para>
                    230:          If you took code from an other Open Source Project, give
                    231:          credit, like:
                    232:        </para>
                    233:        <note><title/>
                    234:           "From FreeBSD"
                    235:        </note>
                    236:       </sect2>
                    237:     </listitem>
                    238:     <listitem>
                    239:       <sect2 id="revert">
                    240:        <title>Do not revert other developer's commits.</title>
                    241:        <para>
                    242:          If you do not agree with another developer's commit, do not
                    243:          revert it on your own. Contact the other developer and explain
1.9       spz       244:          to him or her the issues you have with the commit in question.
                    245:           Ask the other developer to back out the changes instead of
                    246:           doing it yourself.
1.1       jschauma  247:        </para>
                    248:        <para>
1.10      martin    249:          If no agreement can be reached, contact the Core Team
                    250:          &lt;core@NetBSD.org&gt;, which
1.1       jschauma  251:          will serve as mediation authority.
                    252:        </para>
                    253:       </sect2>
                    254:   </listitem>
                    255: </orderedlist>
                    256: 
                    257: </sect1>
                    258: 
                    259: </webpage>

CVSweb <webmaster@jp.NetBSD.org>