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

1.1     ! jschauma    1: <?xml version="1.0"?>
        !             2: <!DOCTYPE webpage
        !             3:   PUBLIC "-//Norman Walsh//DTD Website V2.2//EN"
        !             4:         "http://docbook.sourceforge.net/release/website/2.2/website.dtd">
        !             5: 
        !             6: <webpage id="commit-guidelines">
        !             7: <config param="desc" value="NetBSD Commit Guidelines"/>
        !             8: <config param="cvstag" value="$NetBSD: manpages.xml,v 1.1 2003/12/31 17:26:13 wiz Exp $"/>
        !             9: <config param="rcsdate" value="$Date: 2003/12/31 17:26:13 $"/>
        !            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>
        !            44:     </sect2>
        !            45:    </listitem>
        !            46: 
        !            47:    <listitem>
        !            48:     <sect2 id="intrusive">
        !            49:       <title>
        !            50:        The more intrusive your changes are the higher is the level of
        !            51:        required prior approval.
        !            52:       </title>
        !            53:       <itemizedlist>
        !            54:         <listitem>
        !            55:           <para>
        !            56:            "Obvious" fixes can be committed without any prior discussion
        !            57:            or review. (The definition of "obvious" in the GCC Project is:
        !            58:            "could not possibly cause anyone to object." We adopt this
        !            59:            definition here)
        !            60:          </para>
        !            61:        </listitem>
        !            62:        <listitem>
        !            63:          <para>
        !            64:            All other (i. e. "non-obvious") fixes <emphasis>should</emphasis>
        !            65:            have a review.
        !            66:          </para>
        !            67:        </listitem>
        !            68:        <listitem>
        !            69:          <para>
        !            70:            Implementing (significant) new features requires a prior
        !            71:            discussion on an appropriate technical mailing list.
        !            72:          </para>
        !            73:        </listitem>
        !            74:        <listitem>
        !            75:          <para>
        !            76:            Changing existing interfaces in libraries or in the kernel
        !            77:            requires prior approval by Core.
        !            78:          </para>
        !            79:        </listitem>
        !            80:       </itemizedlist>
        !            81:     </sect2>
        !            82:    </listitem>
        !            83:    <listitem>
        !            84:     <sect2 id="tested">
        !            85:       <title>Commit only code that you have tested.</title>
        !            86:        <para>
        !            87:          Make sure that your code actually works as expected, by
        !            88:          compiling and running the code that is affected by your change
        !            89:          with your system's tools. If you changed a man page, make sure
        !            90:          that groff/nroff creates the formatted man page you expect.
        !            91:        </para>
        !            92:        <para>
        !            93:          For normal commits (to the trunk), test that your code works
        !            94:          on -current. Prior to reqesting a pull-up to a branch, test
        !            95:          the very changes you will request from releng on the respective
        !            96:          release branch.
        !            97:        </para>
        !            98:      </sect2>
        !            99:     </listitem>
        !           100:     <listitem>
        !           101:       <sect2 id="group">
        !           102:        <title>Group commits together that are part of the same fix.</title>
        !           103:        <para>
        !           104:          Rototilling a make variable that affects 50 Makefiles should get
        !           105:           one commit for all of them together.
        !           106:        </para>
        !           107:       </sect2>
        !           108:     </listitem>
        !           109:     <listitem>
        !           110:       <sect2 id="separate">
        !           111:        <title>Each commit should be a separate patch/fix/addition/etc.</title>
        !           112:        <para>
        !           113:          Don't fix 3 bugs with the same commit and roll that into
        !           114:          "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
        !           115:          makes life infinitely easier for releng to pull up fixes since
        !           116:          often not everything applies to a given branch.
        !           117:        </para>
        !           118:       </sect2>
        !           119:     </listitem>
        !           120:     <listitem>
        !           121:       <sect2 id="dont-mix">
        !           122:        <title>
        !           123:          Do not mix functionality or bug-fix patches with
        !           124:          whitespace/layout updates.
        !           125:        </title>
        !           126:         <para>
        !           127:          Do those separately (apart from the general requirement that
        !           128:          changes be made in such a way that it is easy to discern what
        !           129:          each fix did, as described in item 6, there will be pullup
        !           130:          issues with largely changed files from trunk->branch when
        !           131:          mixing whitespace with functionality fixes).
        !           132:        </para>
        !           133:       </sect2>
        !           134:     </listitem>
        !           135:     <listitem>
        !           136:       <sect2 id="document">
        !           137:        <title>Clearly document your changes in the commit log.</title>
        !           138:        <para>
        !           139:          Detail to some degree what was changed and why. Doesn't need
        !           140:          to be a code review/walkthrough but it should be informative
        !           141:          to someone reading the log and looking over the diff in 6
        !           142:          months. Again "fixed some stuff" or "cvs-1.10.0" isn't
        !           143:          acceptable whereas the following example is:
        !           144:        </para>
        !           145:        <note><title/>
        !           146:           "Print useful line number on error while executing .for directive."
        !           147:         </note>
        !           148:        <para>
        !           149:          If your change fixes a PR, document this:
        !           150:        </para>
        !           151:        <note><title/>
        !           152:           "Closes PR bin/6666"
        !           153:         </note>
        !           154:        <para>
        !           155:          If your code has been reviewed by someone else, document this:
        !           156:        </para>
        !           157:        <note><title/>
        !           158:           "Reviewed by &lt;mrg&gt;"
        !           159:        </note>
        !           160:        <para>
        !           161:          (Please note that a good commit log doesn't relieve the need
        !           162:          for good documentation in the program itself.)
        !           163:        </para>
        !           164:       </sect2>
        !           165:     </listitem>
        !           166:     <listitem>
        !           167:       <sect2 id="credit">
        !           168:        <title>Give proper credit.</title>
        !           169:        <para>
        !           170:          If you commit code that had been submitted in a PR, give
        !           171:          proper credit, like:
        !           172:        </para>
        !           173:        <note><title/>
        !           174:            "Code submitted in PR lib/393939 by Joe Doe"
        !           175:        </note>
        !           176:        <para>
        !           177:          Since the commit messages will eventually appear on the
        !           178:          source-changes mailing list which is also available via web,
        !           179:          specifying the e-mail addresses of the PR submitter should
        !           180:          generally be avoided.
        !           181:        </para>
        !           182:        <para>
        !           183:          If you took code from an other Open Source Project, give
        !           184:          credit, like:
        !           185:        </para>
        !           186:        <note><title/>
        !           187:           "From FreeBSD"
        !           188:        </note>
        !           189:       </sect2>
        !           190:     </listitem>
        !           191:     <listitem>
        !           192:       <sect2 id="revert">
        !           193:        <title>Do not revert other developer's commits.</title>
        !           194:        <para>
        !           195:          If you do not agree with another developer's commit, do not
        !           196:          revert it on your own. Contact the other developer and explain
        !           197:          to him or her the issues you have with his commit. Ask him
        !           198:          or her to backout his changes himself.
        !           199:        </para>
        !           200:        <para>
        !           201:          If no agreement can be reached, contact the Technical
        !           202:          Executive Committee &lt;technical-exec@NetBSD.org&gt;, which
        !           203:          will serve as mediation authority.
        !           204:        </para>
        !           205:       </sect2>
        !           206:   </listitem>
        !           207: </orderedlist>
        !           208: 
        !           209: </sect1>
        !           210: 
        !           211: </webpage>

CVSweb <webmaster@jp.NetBSD.org>