Annotation of htdocs/developers/commit-guidelines.xml, revision 1.5.2.1
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.5.2.1 ! hrs 8: <config param="cvstag" value="$NetBSD: commit-guidelines.xml,v 1.6 2006/11/05 19:18:13 heinz Exp $"/>
! 9: <config param="rcsdate" value="$Date: 2006/11/05 19:18:13 $"/>
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>
88: Changing existing interfaces in libraries or in the kernel
89: requires prior approval by Core.
90: </para>
91: </listitem>
92: </itemizedlist>
93: </sect2>
94: </listitem>
95: <listitem>
96: <sect2 id="tested">
97: <title>Commit only code that you have tested.</title>
98: <para>
99: Make sure that your code actually works as expected, by
100: compiling and running the code that is affected by your change
101: with your system's tools. If you changed a man page, make sure
102: that groff/nroff creates the formatted man page you expect.
103: </para>
104: <para>
105: For normal commits (to the trunk), test that your code works
1.5 kano 106: on -current. Prior to requesting a pull-up to a branch, test
1.1 jschauma 107: the very changes you will request from releng on the respective
108: release branch.
109: </para>
110: </sect2>
111: </listitem>
112: <listitem>
113: <sect2 id="group">
114: <title>Group commits together that are part of the same fix.</title>
115: <para>
116: Rototilling a make variable that affects 50 Makefiles should get
117: one commit for all of them together.
118: </para>
119: </sect2>
120: </listitem>
121: <listitem>
122: <sect2 id="separate">
123: <title>Each commit should be a separate patch/fix/addition/etc.</title>
124: <para>
125: Don't fix 3 bugs with the same commit and roll that into
126: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
127: makes life infinitely easier for releng to pull up fixes since
128: often not everything applies to a given branch.
129: </para>
130: </sect2>
131: </listitem>
132: <listitem>
133: <sect2 id="dont-mix">
134: <title>
135: Do not mix functionality or bug-fix patches with
136: whitespace/layout updates.
137: </title>
138: <para>
139: Do those separately (apart from the general requirement that
140: changes be made in such a way that it is easy to discern what
141: each fix did, as described in item 6, there will be pullup
142: issues with largely changed files from trunk->branch when
143: mixing whitespace with functionality fixes).
144: </para>
145: </sect2>
146: </listitem>
147: <listitem>
148: <sect2 id="document">
149: <title>Clearly document your changes in the commit log.</title>
150: <para>
151: Detail to some degree what was changed and why. Doesn't need
152: to be a code review/walkthrough but it should be informative
153: to someone reading the log and looking over the diff in 6
154: months. Again "fixed some stuff" or "cvs-1.10.0" isn't
155: acceptable whereas the following example is:
156: </para>
157: <note><title/>
158: "Print useful line number on error while executing .for directive."
159: </note>
160: <para>
1.5.2.1 ! hrs 161: If your change fixes a PR, document it with an appropriate
! 162: message. Using the template <quote>PR category/bug-id</quote> in
! 163: your commit message will also append it to the respective problem
! 164: report in our bug database:
1.1 jschauma 165: </para>
166: <note><title/>
167: "Closes PR bin/6666"
168: </note>
169: <para>
170: If your code has been reviewed by someone else, document this:
171: </para>
172: <note><title/>
173: "Reviewed by <mrg>"
174: </note>
175: <para>
176: (Please note that a good commit log doesn't relieve the need
177: for good documentation in the program itself.)
178: </para>
179: </sect2>
180: </listitem>
181: <listitem>
182: <sect2 id="credit">
183: <title>Give proper credit.</title>
184: <para>
185: If you commit code that had been submitted in a PR, give
186: proper credit, like:
187: </para>
188: <note><title/>
189: "Code submitted in PR lib/393939 by Joe Doe"
190: </note>
191: <para>
192: Since the commit messages will eventually appear on the
193: source-changes mailing list which is also available via web,
194: specifying the e-mail addresses of the PR submitter should
195: generally be avoided.
196: </para>
197: <para>
198: If you took code from an other Open Source Project, give
199: credit, like:
200: </para>
201: <note><title/>
202: "From FreeBSD"
203: </note>
204: </sect2>
205: </listitem>
206: <listitem>
207: <sect2 id="revert">
208: <title>Do not revert other developer's commits.</title>
209: <para>
210: If you do not agree with another developer's commit, do not
211: revert it on your own. Contact the other developer and explain
212: to him or her the issues you have with his commit. Ask him
213: or her to backout his changes himself.
214: </para>
215: <para>
216: If no agreement can be reached, contact the Technical
217: Executive Committee <technical-exec@NetBSD.org>, which
218: will serve as mediation authority.
219: </para>
220: </sect2>
221: </listitem>
222: </orderedlist>
223:
224: </sect1>
225:
226: </webpage>
CVSweb <webmaster@jp.NetBSD.org>