Document our oral tradition in re what meta information to include at the
bottom of a commit message, and the format that information should take.
This commit is contained in:
Nik Clayton
parent
f9e2cffeab
commit
72210abed1
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=9117
2 changed files with 274 additions and 10 deletions
en_US.ISO8859-1/articles/committers-guide
en_US.ISO_8859-1/articles/committers-guide
|
|
@ -19,7 +19,7 @@
|
|||
</author>
|
||||
</authorgroup>
|
||||
|
||||
<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.54 2001/04/04 00:52:50 kuriyama Exp $</pubdate>
|
||||
<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.55 2001/04/04 08:31:49 nik Exp $</pubdate>
|
||||
|
||||
<copyright>
|
||||
<year>1999</year>
|
||||
|
|
@ -516,11 +516,11 @@
|
|||
</itemizedlist>
|
||||
|
||||
<para>You'll almost certainly get a conflict because
|
||||
of the <literal>$Id: article.sgml,v 1.55 2001-04-04 08:31:49 nik Exp $</literal> (or in FreeBSD's case,
|
||||
of the <literal>$Id: article.sgml,v 1.56 2001-04-04 11:54:01 nik Exp $</literal> (or in FreeBSD's case,
|
||||
<literal>$FreeBSD<!-- stop expansion -->$</literal>) lines, so you'll have to edit
|
||||
the file to resolve the conflict (remove the marker lines and
|
||||
the second <literal>$Id: article.sgml,v 1.55 2001-04-04 08:31:49 nik Exp $</literal> line, leaving the original
|
||||
<literal>$Id: article.sgml,v 1.55 2001-04-04 08:31:49 nik Exp $</literal> line intact).</para>
|
||||
the second <literal>$Id: article.sgml,v 1.56 2001-04-04 11:54:01 nik Exp $</literal> line, leaving the original
|
||||
<literal>$Id: article.sgml,v 1.56 2001-04-04 11:54:01 nik Exp $</literal> line intact).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -1063,7 +1063,7 @@ docs:Documentation Bug:nik:</programlisting>
|
|||
|
||||
<listitem>
|
||||
<para>These are the primary developers and overseers of the
|
||||
DEC Alpha AXP platform.
|
||||
DEC Alpha AXP platform.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
|
@ -2126,6 +2126,138 @@ cvs add: use 'cvs commit' to add this file permanently
|
|||
</example>
|
||||
</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
|
||||
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">
|
||||
<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.</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. If a patch was submitted to a
|
||||
mailing list for review, and the review was favourable,
|
||||
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. 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
|
||||
engineer. If these are your first commits then you should
|
||||
have passed them past your mentor first for approval, and
|
||||
you should list your mentor.</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>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<example>
|
||||
<title>Commit log for a commit based on a PR</title>
|
||||
|
||||
<para>John Smith has submitted a PR containing a patch, which has
|
||||
been applied.</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. The </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>
|
||||
|
||||
<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's not an area of the tree you normally work in, so
|
||||
you've decided to get the change reviewed by the
|
||||
<literal>arch</literal> mailing list.</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</programlisting>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
</qandaset>
|
||||
</sect1>
|
||||
</article>
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@
|
|||
</author>
|
||||
</authorgroup>
|
||||
|
||||
<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.54 2001/04/04 00:52:50 kuriyama Exp $</pubdate>
|
||||
<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.55 2001/04/04 08:31:49 nik Exp $</pubdate>
|
||||
|
||||
<copyright>
|
||||
<year>1999</year>
|
||||
|
|
@ -516,11 +516,11 @@
|
|||
</itemizedlist>
|
||||
|
||||
<para>You'll almost certainly get a conflict because
|
||||
of the <literal>$Id: article.sgml,v 1.55 2001-04-04 08:31:49 nik Exp $</literal> (or in FreeBSD's case,
|
||||
of the <literal>$Id: article.sgml,v 1.56 2001-04-04 11:54:01 nik Exp $</literal> (or in FreeBSD's case,
|
||||
<literal>$FreeBSD<!-- stop expansion -->$</literal>) lines, so you'll have to edit
|
||||
the file to resolve the conflict (remove the marker lines and
|
||||
the second <literal>$Id: article.sgml,v 1.55 2001-04-04 08:31:49 nik Exp $</literal> line, leaving the original
|
||||
<literal>$Id: article.sgml,v 1.55 2001-04-04 08:31:49 nik Exp $</literal> line intact).</para>
|
||||
the second <literal>$Id: article.sgml,v 1.56 2001-04-04 11:54:01 nik Exp $</literal> line, leaving the original
|
||||
<literal>$Id: article.sgml,v 1.56 2001-04-04 11:54:01 nik Exp $</literal> line intact).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -1063,7 +1063,7 @@ docs:Documentation Bug:nik:</programlisting>
|
|||
|
||||
<listitem>
|
||||
<para>These are the primary developers and overseers of the
|
||||
DEC Alpha AXP platform.
|
||||
DEC Alpha AXP platform.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
|
@ -2126,6 +2126,138 @@ cvs add: use 'cvs commit' to add this file permanently
|
|||
</example>
|
||||
</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
|
||||
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">
|
||||
<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.</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. If a patch was submitted to a
|
||||
mailing list for review, and the review was favourable,
|
||||
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. 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
|
||||
engineer. If these are your first commits then you should
|
||||
have passed them past your mentor first for approval, and
|
||||
you should list your mentor.</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>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<example>
|
||||
<title>Commit log for a commit based on a PR</title>
|
||||
|
||||
<para>John Smith has submitted a PR containing a patch, which has
|
||||
been applied.</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. The </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>
|
||||
|
||||
<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's not an area of the tree you normally work in, so
|
||||
you've decided to get the change reviewed by the
|
||||
<literal>arch</literal> mailing list.</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</programlisting>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
</qandaset>
|
||||
</sect1>
|
||||
</article>
|
||||
|
|
|
|||
Loading…
Reference in a new issue