Annotation of htdocs/developers/commit-guidelines.xml, revision 1.12
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.12 ! gutterid 8: <config param="cvstag" value="$NetBSD: commit-guidelines.xml,v 1.11 2024/05/15 13:01:12 riastradh Exp $"/>
! 9: <config param="rcsdate" value="$Date: 2024/05/15 13:01:12 $"/>
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
121: ideally the whole test suite. The logs of the automated
122: test runs are currently available
123: <ulink url="http://www.gson.org/netbsd/bugs/build/">here</ulink>.
124: Long-term regressions (build breakage or failing tests)
125: are not acceptable and changes causing such will be backed
126: out if the regressions are not addressed.
127: </para>
1.1 jschauma 128: </sect2>
129: </listitem>
130: <listitem>
131: <sect2 id="group">
132: <title>Group commits together that are part of the same fix.</title>
133: <para>
134: Rototilling a make variable that affects 50 Makefiles should get
135: one commit for all of them together.
136: </para>
137: </sect2>
138: </listitem>
139: <listitem>
140: <sect2 id="separate">
141: <title>Each commit should be a separate patch/fix/addition/etc.</title>
142: <para>
143: Don't fix 3 bugs with the same commit and roll that into
144: "Fixed some bugs". Fix one, test, commit, rinse, repeat. This
145: makes life infinitely easier for releng to pull up fixes since
146: often not everything applies to a given branch.
147: </para>
148: </sect2>
149: </listitem>
150: <listitem>
151: <sect2 id="dont-mix">
152: <title>
153: Do not mix functionality or bug-fix patches with
154: whitespace/layout updates.
155: </title>
156: <para>
157: Do those separately (apart from the general requirement that
158: changes be made in such a way that it is easy to discern what
159: each fix did, as described in item 6, there will be pullup
160: issues with largely changed files from trunk->branch when
161: mixing whitespace with functionality fixes).
162: </para>
163: </sect2>
164: </listitem>
165: <listitem>
166: <sect2 id="document">
1.8 pooka 167: <title>Clearly document the reasons for your changes in
168: the commit log.</title>
1.1 jschauma 169: <para>
1.8 pooka 170: Detail to some degree what was changed and why. This
171: doesn't need to be a code review/walkthrough but it should
172: be informative to someone reading the log and looking
173: over the diff in 6 months. The focus should be on "why"
174: since the target audience reading the logs can usually
175: figure out "what" from looking the diffs. As an exercise,
176: consider the difference of usefulness between "set i to
177: 1" and "initialize iterator correctly to fix a rarely
178: triggering bug in memory handling".
179: </para>
180:
181: <para>
182: Also, "fixed some stuff" or "cvs-1.10.0" isn't informative
183: whereas the following example is:
1.1 jschauma 184: </para>
185: <note><title/>
186: "Print useful line number on error while executing .for directive."
187: </note>
188: <para>
1.6 heinz 189: If your change fixes a PR, document it with an appropriate
190: message. Using the template <quote>PR category/bug-id</quote> in
191: your commit message will also append it to the respective problem
192: report in our bug database:
1.1 jschauma 193: </para>
194: <note><title/>
195: "Closes PR bin/6666"
196: </note>
197: <para>
198: If your code has been reviewed by someone else, document this:
199: </para>
200: <note><title/>
201: "Reviewed by <mrg>"
202: </note>
203: <para>
204: (Please note that a good commit log doesn't relieve the need
205: for good documentation in the program itself.)
206: </para>
207: </sect2>
208: </listitem>
209: <listitem>
210: <sect2 id="credit">
211: <title>Give proper credit.</title>
212: <para>
213: If you commit code that had been submitted in a PR, give
214: proper credit, like:
215: </para>
216: <note><title/>
217: "Code submitted in PR lib/393939 by Joe Doe"
218: </note>
219: <para>
220: Since the commit messages will eventually appear on the
221: source-changes mailing list which is also available via web,
222: specifying the e-mail addresses of the PR submitter should
223: generally be avoided.
224: </para>
225: <para>
226: If you took code from an other Open Source Project, give
227: credit, like:
228: </para>
229: <note><title/>
230: "From FreeBSD"
231: </note>
232: </sect2>
233: </listitem>
234: <listitem>
235: <sect2 id="revert">
236: <title>Do not revert other developer's commits.</title>
237: <para>
238: If you do not agree with another developer's commit, do not
239: revert it on your own. Contact the other developer and explain
1.9 spz 240: to him or her the issues you have with the commit in question.
241: Ask the other developer to back out the changes instead of
242: doing it yourself.
1.1 jschauma 243: </para>
244: <para>
1.10 martin 245: If no agreement can be reached, contact the Core Team
246: <core@NetBSD.org>, which
1.1 jschauma 247: will serve as mediation authority.
248: </para>
249: </sect2>
250: </listitem>
251: </orderedlist>
252:
253: </sect1>
254:
255: </webpage>
CVSweb <webmaster@jp.NetBSD.org>