From: Gokturk Yuksek <gokt...@binghamton.edu> This section includes the content from the "Commit message format" subsection on Gentoo git workflow wiki page, combines it with some of the information that was part of the old ChangeLog section in devmanual and expands on those based on the feedback from the developers on the gentoo-dev@g.o mailing list.
Gentoo-Bug: https://bugs.gentoo.org/show_bug.cgi?id=558642 Reviewed-by: NP-Hardass <np-hard...@gentoo.org> Signed-off-by: Gokturk Yuksek <gokt...@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> -- 2.4.10
