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