Git Commit Message Format

From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id 9117858973 for ; Fri, 5 Feb 2016 12:59:48 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id DD06921C095; Fri, 5 Feb 2016 12:59:34 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 6FCE921C095 for ; Fri, 5 Feb 2016 12:59:29 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 7463B340B1C for ; Fri, 5 Feb 2016 12:59:23 +0000 (UTC) Received: from localhost.localdomain (localhost [127.0.0.1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 1C5B11074 for ; Fri, 5 Feb 2016 12:59:19 +0000 (UTC) From: "Ulrich Müller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" Message-ID: <1454677102.fb7db633772884dd156c1fe0cb2c22e312a8a248.ulm@gentoo> Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/ X-VCS-Repository: proj/devmanual X-VCS-Files: ebuild-maintenance/text.xml X-VCS-Directories: ebuild-maintenance/ X-VCS-Committer: ulm X-VCS-Committer-Name: Ulrich Müller X-VCS-Revision: fb7db633772884dd156c1fe0cb2c22e312a8a248 X-VCS-Branch: master Date: Fri, 5 Feb 2016 12:59:19 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: f657d14a-f738-485d-8e48-072199a93776 X-Archives-Hash: 95a7b9159be2382d33ad2c68ff0a6776 commit: fb7db633772884dd156c1fe0cb2c22e312a8a248 Author: Gokturk Yuksek binghamton edu> AuthorDate: Thu Feb 4 00:57:48 2016 +0000 Commit: Ulrich Müller gentoo 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 , 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 g.o mailing list. Gentoo-Bug: https://bugs.gentoo.org/show_bug.cgi?id=558642 Reviewed-by: NP-Hardass gentoo.org> Signed-off-by: Gokturk Yuksek 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. +Git Commit Message Format + + +

+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. +

+ +

+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: + +

${CATEGORY}/${PN}:Single Package (Note that repoman commit +automatically inserts this for you)
${CATEGORY}: Package Category
profiles: Profile Directory
${ECLASS}.eclass: Eclass Directotry
licenses: Licenses Directory
metadata: Metadata Directory

+ +For packages where ${CATEGORY}/${PN}: 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 +#BUG-ID. If you are modifying keywords, clearly state what +keywords are added/removed. + + +By default, lines starting with # are considered to be comments +by git and not included in the commit message. Make sure that a new +line does not start with #BUG-ID. Optionally, git can be +configured to use a different character for comments by changing the +commentchar option. + +

+ +

+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. +

+ +

+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 + +Linux Kernel patch guideline. Additionally, the following tags +are used in Gentoo: + +

Gentoo-Bug: 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. +
Package-Manager: This is automatically inserted by +repoman commit and it specifies the version of +sys-apps/portage on the system.
RepoMan-Options: This is automatically inserted by +repoman commit and records the options passed to repoman (such +as --force) for the commit.

+ +

+When committing user +contributions, 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 Suggested-By or +Reported-By:when entering such information to the commit +message. +

+ +

+An example commit message is shown below: +

+ +

+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
+

+ + + + + Git Commit Policy