Split out and expand upon the committer guide's discussion of commit logs.
Some discussion about how to write an appropriate commit log description should be included. The section currently only discusses the 'meta data'.
This commit is contained in:
Eitan Adler
parent
f24698933b
commit
ee4b3bc705
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=43157
1 changed files with 204 additions and 186 deletions
|
|
@ -2178,6 +2178,210 @@ ControlPersist yes</screen>
|
|||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="commit-log-message">
|
||||
<title>Commit Log Messages</title>
|
||||
|
||||
<para>This section contains some suggestions and traditions for
|
||||
how commit logs are formatted.</para>
|
||||
|
||||
<para>As well as including an informative message with each
|
||||
commit you may need to include some additional
|
||||
information.</para>
|
||||
|
||||
<para>This information consists of one or more lines
|
||||
containing the key word or phrase, a colon, tabs for
|
||||
formatting, and then the additional information.</para>
|
||||
|
||||
<para>The key words or phrases are:</para>
|
||||
|
||||
<informaltable frame="none" pgwide="1">
|
||||
<tgroup cols="2">
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><literal>PR:</literal></entry>
|
||||
<entry>The problem report (if any) which is affected
|
||||
(typically, by being closed) by this
|
||||
commit. Only include one PR per line as the
|
||||
automated scripts which parse this line can not
|
||||
understand more than one.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Submitted by:</literal></entry>
|
||||
<entry><para>The name and e-mail address of the person
|
||||
that submitted the fix; for committers, just the
|
||||
username on the &os; cluster.</para>
|
||||
<para>If the submitter is the maintainer of the port
|
||||
to which you are commiting include "(maintainer)"
|
||||
after the email address.</para>
|
||||
<para>Avoid obfuscating the
|
||||
email address of the submitter as this adds
|
||||
additional work when searching logs.</para>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Reviewed by:</literal></entry>
|
||||
<entry>The name and e-mail address of the person or
|
||||
people that reviewed the change; for committers,
|
||||
just the username on the &os; cluster. If a
|
||||
patch was submitted to a mailing list for review,
|
||||
and the review was favorable, then just include
|
||||
the list name.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Approved by:</literal></entry>
|
||||
<entry><para>The name and e-mail address of the person or
|
||||
people that approved the change; for committers,
|
||||
just the username on the &os; cluster. It is
|
||||
customary to get prior approval for a commit if it
|
||||
is to an area of the tree to which you do not
|
||||
usually commit. In addition, during the run up to
|
||||
a new release all commits
|
||||
<emphasis>must</emphasis> be approved by the
|
||||
release engineering team.</para>
|
||||
|
||||
<para>If these are your first
|
||||
commits then you should have passed them past your
|
||||
mentor first, and you should list your mentor, as
|
||||
in ``<replaceable>username-of-mentor</replaceable>
|
||||
<literal>(mentor)</literal>''.</para>
|
||||
|
||||
<para>If a team approved these commits
|
||||
then include the team
|
||||
name followed by the username of the approver in
|
||||
parenticies. For example: ``<replaceable>re@
|
||||
(username)</replaceable>``</para></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Obtained from:</literal></entry>
|
||||
<entry>The name of the project (if any) from which
|
||||
the code was obtained. Do not use this line for the
|
||||
name of an indivual person.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>MFC after:</literal></entry>
|
||||
<entry>If you wish to receive an e-mail reminder to
|
||||
<acronym>MFC</acronym> at a later date, specify
|
||||
the number of days, weeks, or months after which
|
||||
an <acronym>MFC</acronym> is planned.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Security:</literal></entry>
|
||||
<entry>If the change is related to a security
|
||||
vulnerability or security exposure, include one or
|
||||
more references or a description of the
|
||||
issue. If possible, include a VuXML URL or a CVE id.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Commit Based on a PR</title>
|
||||
|
||||
<para>You want to commit a change based on a PR submitted
|
||||
by John Smith containing a patch. The end of the commit
|
||||
message should look something like this.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
PR: foo/12345
|
||||
Submitted by: John Smith <John.Smith@example.com></programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Commit Needing Review</title>
|
||||
|
||||
<para>You want to change the virtual memory system. You
|
||||
have posted patches to the appropriate mailing list (in
|
||||
this case, <literal>freebsd-arch</literal>) and the
|
||||
changes have been approved.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
Reviewed by: -arch</programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Commit Needing Approval</title>
|
||||
|
||||
<para>You want to commit a port
|
||||
You have collaborated with
|
||||
the listed MAINTAINER, who has told you to go ahead and
|
||||
commit.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
Approved by: <replaceable>abc</replaceable> (maintainer)</programlisting>
|
||||
|
||||
<para>Where <replaceable>abc</replaceable> is the account
|
||||
name of the person who approved.</para>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Commit Bringing in Code from
|
||||
OpenBSD</title>
|
||||
|
||||
<para>You want to commit some code based on work done in
|
||||
the OpenBSD project.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
Obtained from: OpenBSD</programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Change to &os.current; with a
|
||||
Planned Commit to &os.stable; to Follow at a Later
|
||||
Date.</title>
|
||||
|
||||
<para>You want to commit some code which will be merged
|
||||
from &os.current; into the &os.stable; branch after two
|
||||
weeks.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
MFC after: <replaceable>2 weeks</replaceable></programlisting>
|
||||
|
||||
<para>Where <replaceable>2</replaceable> is the number of
|
||||
days, weeks, or months after which an
|
||||
<acronym>MFC</acronym> is planned. The
|
||||
<replaceable>weeks</replaceable> option may be
|
||||
<literal>day</literal>, <literal>days</literal>,
|
||||
<literal>week</literal>, <literal>weeks</literal>,
|
||||
<literal>month</literal>, <literal>months</literal>, or
|
||||
may be left off (in which case, days will be
|
||||
assumed).</para>
|
||||
</example>
|
||||
|
||||
<para>In some cases you may need to combine some of
|
||||
these.</para>
|
||||
|
||||
<para>Consider the situation where a user has submitted a PR
|
||||
containing code from the NetBSD project. You are looking
|
||||
at the PR, but it is not an area of the tree you normally
|
||||
work in, so you have decided to get the change reviewed by
|
||||
the <literal>arch</literal> mailing list. Since the
|
||||
change is complex, you opt to <acronym>MFC</acronym> after
|
||||
one month to allow adequate testing.</para>
|
||||
|
||||
<para>The extra information to include in the commit would
|
||||
look something like</para>
|
||||
<example>
|
||||
<title>Example Combined Commit Log</title>
|
||||
<programlisting>PR: foo/54321
|
||||
Submitted by: John Smith <John.Smith@example.com>
|
||||
Reviewed by: -arch
|
||||
Obtained from: NetBSD
|
||||
MFC after: 1 month</programlisting>
|
||||
</example>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="pref-license">
|
||||
<title>Preferred License for New Files</title>
|
||||
|
||||
|
|
@ -4398,192 +4602,6 @@ bak/packages packages from last complete <major_version> run on <arch&
|
|||
</answer>
|
||||
</qandaentry>
|
||||
|
||||
<qandaentry>
|
||||
<question>
|
||||
<para>What <quote>meta</quote> information should I include
|
||||
in a commit message?</para>
|
||||
</question>
|
||||
|
||||
<answer>
|
||||
<para>As well as including an informative message with each
|
||||
commit you may need to include some additional information
|
||||
as well.</para>
|
||||
|
||||
<para>This information consists of one or more lines
|
||||
containing the key word or phrase, a colon, tabs for
|
||||
formatting, and then the additional information.</para>
|
||||
|
||||
<para>The key words or phrases are:</para>
|
||||
|
||||
<informaltable frame="none" pgwide="1">
|
||||
<tgroup cols="2">
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><literal>PR:</literal></entry>
|
||||
<entry>The problem report (if any) which is affected
|
||||
(typically, by being closed) by this
|
||||
commit.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Submitted by:</literal></entry>
|
||||
<entry>The name and e-mail address of the person
|
||||
that submitted the fix; for committers, just the
|
||||
username on the &os; cluster.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Reviewed by:</literal></entry>
|
||||
<entry>The name and e-mail address of the person or
|
||||
people that reviewed the change; for committers,
|
||||
just the username on the &os; cluster. If a
|
||||
patch was submitted to a mailing list for review,
|
||||
and the review was favorable, then just include
|
||||
the list name.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Approved by:</literal></entry>
|
||||
<entry>The name and e-mail address of the person or
|
||||
people that approved the change; for committers,
|
||||
just the username on the &os; cluster. It is
|
||||
customary to get prior approval for a commit if it
|
||||
is to an area of the tree to which you do not
|
||||
usually commit. In addition, during the run up to
|
||||
a new release all commits
|
||||
<emphasis>must</emphasis> be approved by the
|
||||
release engineering team. If these are your first
|
||||
commits then you should have passed them past your
|
||||
mentor first, and you should list your mentor, as
|
||||
in ``<replaceable>username-of-mentor</replaceable>
|
||||
<literal>(mentor)</literal>''.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Obtained from:</literal></entry>
|
||||
<entry>The name of the project (if any) from which
|
||||
the code was obtained.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>MFC after:</literal></entry>
|
||||
<entry>If you wish to receive an e-mail reminder to
|
||||
<acronym>MFC</acronym> at a later date, specify
|
||||
the number of days, weeks, or months after which
|
||||
an <acronym>MFC</acronym> is planned.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>Security:</literal></entry>
|
||||
<entry>If the change is related to a security
|
||||
vulnerability or security exposure, include one or
|
||||
more references or a description of the
|
||||
issue.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Commit Based on a PR</title>
|
||||
|
||||
<para>You want to commit a change based on a PR submitted
|
||||
by John Smith containing a patch. The end of the commit
|
||||
message should look something like this.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
PR: foo/12345
|
||||
Submitted by: John Smith <John.Smith@example.com></programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Commit Needing Review</title>
|
||||
|
||||
<para>You want to change the virtual memory system. You
|
||||
have posted patches to the appropriate mailing list (in
|
||||
this case, <literal>freebsd-arch</literal>) and the
|
||||
changes have been approved.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
Reviewed by: -arch</programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Commit Needing Approval</title>
|
||||
|
||||
<para>You want to commit a change to a section of the tree
|
||||
with a MAINTAINER assigned. You have collaborated with
|
||||
the listed MAINTAINER, who has told you to go ahead and
|
||||
commit.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
Approved by: <replaceable>abc</replaceable></programlisting>
|
||||
|
||||
<para>Where <replaceable>abc</replaceable> is the account
|
||||
name of the person who approved.</para>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Commit Bringing in Code from
|
||||
OpenBSD</title>
|
||||
|
||||
<para>You want to commit some code based on work done in
|
||||
the OpenBSD project.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
Obtained from: OpenBSD</programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Commit Log for a Change to &os.current; with a
|
||||
Planned Commit to &os.stable; to Follow at a Later
|
||||
Date.</title>
|
||||
|
||||
<para>You want to commit some code which will be merged
|
||||
from &os.current; into the &os.stable; branch after two
|
||||
weeks.</para>
|
||||
|
||||
<programlisting>...
|
||||
|
||||
MFC after: <replaceable>2 weeks</replaceable></programlisting>
|
||||
|
||||
<para>Where <replaceable>2</replaceable> is the number of
|
||||
days, weeks, or months after which an
|
||||
<acronym>MFC</acronym> is planned. The
|
||||
<replaceable>weeks</replaceable> option may be
|
||||
<literal>day</literal>, <literal>days</literal>,
|
||||
<literal>week</literal>, <literal>weeks</literal>,
|
||||
<literal>month</literal>, <literal>months</literal>, or
|
||||
may be left off (in which case, days will be
|
||||
assumed).</para>
|
||||
</example>
|
||||
|
||||
<para>In some cases you may need to combine some of
|
||||
these.</para>
|
||||
|
||||
<para>Consider the situation where a user has submitted a PR
|
||||
containing code from the NetBSD project. You are looking
|
||||
at the PR, but it is not an area of the tree you normally
|
||||
work in, so you have decided to get the change reviewed by
|
||||
the <literal>arch</literal> mailing list. Since the
|
||||
change is complex, you opt to <acronym>MFC</acronym> after
|
||||
one month to allow adequate testing.</para>
|
||||
|
||||
<para>The extra information to include in the commit would
|
||||
look something like</para>
|
||||
|
||||
<programlisting>PR: foo/54321
|
||||
Submitted by: John Smith <John.Smith@example.com>
|
||||
Reviewed by: -arch
|
||||
Obtained from: NetBSD
|
||||
MFC after: 1 month</programlisting>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
|
||||
<qandaentry>
|
||||
<question>
|
||||
<para>How do I access
|
||||
|
|
|
|||
Loading…
Reference in a new issue