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 <mrg>"
! 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 <technical-exec@NetBSD.org>, 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>