From: "Ulrich Müller" <ulm@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/
Date: Fri, 5 Feb 2016 12:59:19 +0000 (UTC) [thread overview]
Message-ID: <1454677102.fb7db633772884dd156c1fe0cb2c22e312a8a248.ulm@gentoo> (raw)
commit: fb7db633772884dd156c1fe0cb2c22e312a8a248
Author: Gokturk Yuksek <gokturk <AT> binghamton <DOT> edu>
AuthorDate: Thu Feb 4 00:57:48 2016 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Feb 5 12:58:22 2016 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=fb7db633
ebuid-maintenance: add a new section called "Git Commit Message Format" #558642
Most of this section is derived from the "Commit message format"
subsection of the "Gentoo git workflow" wiki page
<https://wiki.gentoo.org/wiki/Gentoo_git_workflow>, which is released
under the CC-BY-SA-3.0 license.
Parts of the old ChangeLog section in the devmanual are also included,
as well as feedback from developers on the gentoo-dev <AT> g.o mailing list.
Gentoo-Bug: https://bugs.gentoo.org/show_bug.cgi?id=558642
Reviewed-by: NP-Hardass <np-hardass <AT> gentoo.org>
Signed-off-by: Gokturk Yuksek <gokturk <AT> binghamton.edu>
ebuild-maintenance/text.xml | 113 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 113 insertions(+)
diff --git a/ebuild-maintenance/text.xml b/ebuild-maintenance/text.xml
index 26cca2f..5b2abee 100644
--- a/ebuild-maintenance/text.xml
+++ b/ebuild-maintenance/text.xml
@@ -96,6 +96,119 @@ work on those architectures.
</subsection>
<subsection>
+<title>Git Commit Message Format</title>
+<body>
+
+<p>
+It is important to format the commit messages properly so that they
+communicate the changes to the reader in a clear and concise
+way. Additionally, consistency in message format allows for easier
+parsing by external tools. The first line of the commit message should
+contain a brief summary of the changes, followed by an empty new
+line. From the third line onward should be a detailed, multiline
+explanation of the changes introduced by the commit. At the very end,
+auxiliary information such as the bugs related to the commit,
+contributors, and reviewers should be listed using RFC822/git style
+tags. The length of the lines in the message should be 70-75
+characters at maximum.
+</p>
+
+<p>
+The summary line should start with referencing what is affected by the
+change followed by a colon ':' character. Use the rules in the
+following list to determine the proper format based on what has
+changed, substituting the package, category and eclass names
+appropriately:
+
+<ul>
+<li><c>${CATEGORY}/${PN}:</c>Single Package (Note that <c>repoman commit</c>
+automatically inserts this for you)</li>
+<li><c>${CATEGORY}:</c> Package Category</li>
+<li><c>profiles:</c> Profile Directory</li>
+<li><c>${ECLASS}.eclass:</c> Eclass Directotry</li>
+<li><c>licenses:</c> Licenses Directory</li>
+<li><c>metadata:</c> Metadata Directory</li>
+</ul>
+
+For packages where <c>${CATEGORY}/${PN}:</c> is long, the line length
+limit can be exceeded, if absolutely necessary, to ensure a more
+useful summary line. If a commit affects multiple directories, prepend
+the message with which reflects the intention of the change best. If
+there are any bugs on Gentoo Bugzilla associated with the commit, id
+of the bug can be appended to the summary line using the format
+<c>#BUG-ID</c>. If you are modifying keywords, clearly state what
+keywords are added/removed.
+
+<warning>
+By default, lines starting with <c>#</c> are considered to be comments
+by git and not included in the commit message. Make sure that a new
+line does not start with <c>#BUG-ID</c>. Optionally, git can be
+configured to use a different character for comments by changing the
+<c>commentchar</c> option.
+</warning>
+</p>
+
+<p>
+For non-trivial commits, the message should contain a detailed
+explanation of what the commit intends to change, why it is required,
+and how it is accomplished, along with any other supplementary
+information.
+</p>
+
+<p>
+Finally the commit message should list auxiliary information such as
+people who are involved in authoring, suggesting, reviewing and
+testing the changes, and revelant bugs. Use RFC822/git style tags as
+explained in the
+<uri link="https://www.kernel.org/doc/Documentation/SubmittingPatches">
+Linux Kernel patch guideline</uri>. Additionally, the following tags
+are used in Gentoo:
+
+<ul>
+<li><c>Gentoo-Bug:</c> Use this to reference bugs in Gentoo Bugzilla
+by either the bug ID or the bugzilla URI. Multiple bugs can be
+referenced by inserting more tags of this type or separating bug IDs
+with a comma in the same tag. The bug IDs may include an optional '#'
+prefix. There is no consensus on referencing bugs in the summary line
+versus referencing with a tag in the message body. The developer has
+the option to choose either.
+</li>
+<li><c>Package-Manager:</c> This is automatically inserted by
+<c>repoman commit</c> and it specifies the version of
+<pkg>sys-apps/portage</pkg> on the system.</li>
+<li><c>RepoMan-Options:</c> This is automatically inserted by
+<c>repoman commit</c> and records the options passed to repoman (such
+as --force) for the commit.</li>
+</ul>
+</p>
+
+<p>
+When committing <uri link="::ebuild-writing/user-submitted">user
+contributions</uri>, make sure to credit them in your commit message
+with the user's full name and email address. Be aware and respectful
+of their privacy: some users prefer to be only known by a
+nickname. Take advantage of the tags such as <c>Suggested-By</c> or
+<c>Reported-By:</c>when entering such information to the commit
+message.
+</p>
+
+<p>
+An example commit message is shown below:
+</p>
+
+<pre caption="Example commit message">
+app-misc/foo: version bump to 0.5
+
+This also adds a new USE flag 'bar' which controls the
+new bar functionality introduced with this version.
+
+Gentoo-Bug: 01234
+</pre>
+
+</body>
+</subsection>
+
+<subsection>
<title>Git Commit Policy</title>
<body>
next reply other threads:[~2016-02-05 12:59 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-02-05 12:59 Ulrich Müller [this message]
-- strict thread matches above, loose matches on Subject: below --
2020-01-23 8:40 [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/ Ulrich Müller
2017-09-25 4:40 Göktürk Yüksek
2017-09-25 4:40 Göktürk Yüksek
2017-07-29 20:48 Göktürk Yüksek
2017-01-22 20:45 Göktürk Yüksek
2016-11-20 20:46 Göktürk Yüksek
2016-08-18 9:01 Ulrich Müller
2016-05-22 8:35 Ulrich Müller
2016-05-01 3:49 Göktürk Yüksek
2016-04-24 0:47 Göktürk Yüksek
2016-04-23 19:26 Göktürk Yüksek
2016-04-19 10:40 Ulrich Müller
2016-02-05 12:59 Ulrich Müller
2016-02-05 12:59 Ulrich Müller
2016-02-05 12:59 Ulrich Müller
2016-02-05 12:59 Ulrich Müller
2016-02-05 12:59 Ulrich Müller
2016-02-05 12:59 Ulrich Müller
2016-02-05 12:59 Ulrich Müller
2015-05-09 15:22 Ulrich Müller
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1454677102.fb7db633772884dd156c1fe0cb2c22e312a8a248.ulm@gentoo \
--to=ulm@gentoo.org \
--cc=gentoo-commits@lists.gentoo.org \
--cc=gentoo-dev@lists.gentoo.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox