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