On 5/14/20 6:47 PM, Joseph Myers wrote:
On Thu, 14 May 2020, Martin Liška wrote:
On 5/13/20 7:53 PM, Joseph Myers wrote:
On Wed, 13 May 2020, Martin Liška wrote:
I'm sending the gcc-changelog relates scripts which should be added to
contrib
folder. The patch contains:
- git_check_commit.py - checking script that verifies git message format
We need a documentation patch to contribute.html or gitwrite.html that
describes the exact commit message format being used.
Sure, I'm sending patch for that.
Thanks. There are references to author timestamps there. The date in a
ChangeLog entry should always be a commit timestamp, not an author one, so
author timestamps present either in commit messages or in the git commit
metadata should be ignored, with only the committer timestamps from the
git commit metadata being used when generating ChangeLog files.
You are fully right, a committer date is what should be used.
Fixed in the documentation, note that the scripts use committed date.
Martin
diff --git a/htdocs/codingconventions.html b/htdocs/codingconventions.html
index f4732ef6..d2e73962 100644
--- a/htdocs/codingconventions.html
+++ b/htdocs/codingconventions.html
@@ -112,9 +112,14 @@ maintained and kept up to date. In particular:</p>
<h2 id="ChangeLogs">ChangeLogs</h2>
-<p>GCC requires ChangeLog entries for documentation changes; for the web
-pages (apart from <code>java/</code> and <code>libstdc++/</code>) the CVS
-commit logs are sufficient.</p>
+<p>
+ChangeLog entries are part of git commit messages and are automatically put
+into a corresponding ChangeLog file. A ChangeLog template can be easily generated
+with <code>./contrib/mklog</code> script. GCC offers a checking script that
+verifies a proper ChangeLog formatting (see <code>git gcc-verify</code> git alias).
+for a particular git commit. The checking script covers most commonly used ChangeLog
+formats and the following paragraphs explain what it supports.
+</p>
<p>See also what the <a
href="http://www.gnu.org/prep/standards_toc.html";>GNU Coding
@@ -124,19 +129,95 @@ in comments rather than the ChangeLog, though a single line overall
description of the changes may be useful above the ChangeLog entry for
a large batch of changes.</p>
-<p>For changes that are ported from another branch, we recommend to
-use a single entry whose body contains a verbatim copy of the original
-entries describing the changes on that branch, possibly preceded by a
-single-line overall description of the changes.</p>
+<h3>Components</h3>
+
+<ul>
+ <li><code class="other">git_description</code> - a leading text with git commit description</li>
+ <li><code class="other">committer_timestamp</code> - line with timestamp and an author name and email (2 spaces before and after name) <br>
+ example: <code class="other">2020-04-23␣␣Martin Liska␣␣<mli...@suse.cz></code></li>
+ <li><code class="other">additional_author</code> - line with additional commit author name and email (starting with a tabular and 4 spaces) <br>
+ example: <code class="other">\t␣␣␣␣Martin Liska␣␣<mli...@suse.cz></code></li>
+ <li><code class="other">changelog_location</code> - a location to a ChangeLog file <br>
+ supported formats: <code class="other">a/b/c/ChangeLog</code>, <code class="other">a/b/c/ChangeLog:</code>, <code class="other">a/b/c/</code> (where ChangeLog file lives in the folder), <code class="other">\ta/b/c/</code> and <code class="other">a/b/c</code></li>
+ <li><code class="other">pr_entry</code> - bug report reference <br>
+ example: <code class="other">\tPR component/12345</code></li>
+ <li><code class="other">changelog_file</code> - a modified file mentined in a ChangeLog:
+ supported formats: <code class="other">\t* a/b/c/file.c:</code>, <code class="other">\t* a/b/c/file.c (function):</code>, <code class="other">\t* a/b/c/file1.c, a/b/c/file2.c:</code></li>
+ <li><code class="other">changelog_file_comment</code> - line that follows a <code class="other">changelog_file</code> with description of changes in the file;
+ must start with <code class="other">\t</code></li>
+ <li><code class="other">co_authored_by</code> - <a href="https://help.github.com/en/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors";>GitHub format</a> for a Co-Authored-By</li>
+</ul>
+
+<h3>Format rules</h3>
+
+<ul>
+ <li><code class="other">git_description</code> - optional; ends right before one of the other compoments is found</li>
+ <li><code class="other">committer_timestamp</code> - optional; when found before a <code class="other">changelog_file</code>, then it is added
+ to each changelog entry</li>
+ <li><code class="other">additional_author</code> - optional</li>
+ <li><code class="other">changelog_location</code> - optional; parser attempts to identify ChangeLog file based
+ on modified files; <code class="other">$changelog_location</code> belonging to a different ChangeLog must
+ be separated with an empty line</li>
+ <li><code class="other">pr_entry</code> - optional; can contain any number of PR entries</li>
+ <li><code class="other">changelog_file</code> - each <code>changelog_location</code> must contain at least one file</li>
+ <li><code class="other">changelog_file_comment</code> - optional</li>
+ <li><code class="other">co_authored_by</code> - optional, can contain more than one</li>
+</ul>
+
+<h3>Documented behaviour</h3>
+
+<ul>
+ <li>a missing <code class="other">changelog_location</code> file location can be deduced based on group of <code class="other">changelog_file</code>s</li>
+ <li>script automatically generates missing "New file." entries for files that are added in a commit</li>
+ <li>changed files that are not mentioned in a ChangeLog file generate an error</li>
+ <li>similarly for unchanged files that are mentioned in a ChangeLog file</li>
+ <li>a commit author and committer date stamp can be automatically deduced from a git commit - we recommend to use it</li>
+ <li><code class="other">co_authored_by</code> is added to each ChangeLog entry</li>
+ <li>a PR component is checked against list of valid components</li>
+ <li><code>ChangeLog</code> files, <code>DATESTAMP</code>, <code>BASE-VER</code> and <code>DEV-PHASE</code> can be modified only separately from other files</li>
+</ul>
-<p>There is no established convention on when ChangeLog entries are to
-be made for testsuite changes; see messages <a
-href="https://gcc.gnu.org/ml/gcc/2000-09/msg00287.html";>1</a> and <a
-href="https://gcc.gnu.org/ml/gcc/2000-09/msg00290.html";>2</a>.</p>
+<h3>Example patch</h3>
-<p>If your change fixes a PR, put <code>PR java/58</code> (where
-<code>java/58</code> is the actual number of the PR) at the top
-of the ChangeLog entry.</p>
+<pre><code>This patch adds a second movk pattern that models the instruction
+as a "normal" and/ior operation rather than an insertion. It fixes
+the third insv_1.c failure in PR87763, which was a regression from
+GCC 8.
+
+2020-02-06 John Foo <j...@example.com>
+
+gcc/
+ PR target/87763
+ * config/aarch64/aarch64-protos.h (aarch64_movk_shift): Declare.
+ * config/aarch64/aarch64.c (aarch64_movk_shift): New function.
+ * config/aarch64/aarch64.md (aarch64_movk<mode>): New pattern.
+
+gcc/testsuite/
+ PR target/87763
+ * gcc.target/aarch64/movk_2.c: New test.
+
+Co-Authored-By: Jack Bar <j...@example.com>
+</code></pre>
+
+<h3>Tokenized patch</h3>
+
+<pre>
+<code>$git_description
+
+$committer_timestamp
+
+$changelog_location
+$pr_entry
+$changelog_file
+$changelog_file
+$changelog_file
+
+$changelog_location
+$pr_entry
+$changelog_file
+
+$co_authored_by</code>
+</pre>
<h2 id="Portability">Portability</h2>
@@ -201,7 +282,6 @@ minimize the number of function prototypes, by defining them before
their first use. Function prototypes should only be used when
necessary, to break mutually recursive cycles.</p>
-
<h2 id="Makefiles">Makefiles</h2>
<p><code>touch</code> should never be used in GCC Makefiles. Instead
diff --git a/htdocs/contribute.html b/htdocs/contribute.html
index 3d03b9d1..80a4470e 100644
--- a/htdocs/contribute.html
+++ b/htdocs/contribute.html
@@ -177,22 +177,10 @@ testcases cannot be added.
<dt>ChangeLog</dt>
<dd>
-A ChangeLog entry as plaintext; see the various ChangeLog files for
-format and content, and the <a href="codingconventions.html">GCC
+A ChangeLog entry as plaintext; see the <a href="codingconventions.html#ChangeLogs">GCC
coding conventions</a> and <a
href="http://www.gnu.org/prep/standards_toc.html";>GNU Coding
-Standards</a> for further information. The ChangeLog entries should
-be plaintext rather than part of the patch since the top of the
-ChangeLog changes rapidly and a patch to the ChangeLog would probably
-no longer apply by the time your patch is reviewed.
-If your change fixes a PR, put text in the ChangeLog entry mentioning
-the PR. Our infrastructure understands how to
-extract this information and automatically append the commit log to
-the PR. In order to be recognized, the text must fit a particular
-form. It must start with "PR", and then must include the category
-and PR number. For instance, <code>PR java/2369</code> is
-valid. Multiple PRs can be mentioned in a single message.
-</dd>
+Standards</a> for further information.</dd>
<dt>Bootstrapping and testing</dt>
<dd>
diff --git a/htdocs/gitwrite.html b/htdocs/gitwrite.html
index 97d60870..791213a5 100644
--- a/htdocs/gitwrite.html
+++ b/htdocs/gitwrite.html
@@ -25,7 +25,6 @@ maintainers and significant developers.</p>
<li><a href="#checkin">Checking in a change</a></li>
<li><a href="#example">Example check-in session</a></li>
<li><a href="#branches">Creating and using branches</a></li>
- <li><a href="#changelog">git-merge-changelog</a></li>
<li><a href="#vendor">Personal and Vendor branches</a></li>
<li><a href="#account">Tips&Tricks around your account</a></li>
</ol>
@@ -237,9 +236,10 @@ pull</code>" before attempting a checkin; this will save you a little
time if someone else has modified the source tree since the last time
you synced your sources.</li>
-<li>Apply the patch to your local tree and update the ChangeLog file.
-Use the current date/time for the ChangeLog entry, not the time that
-the patch was submitted.</li>
+<li>Apply the patch to your local tree. ChangeLog entries will be
+automatically added to the corresponding ChangeLog files based
+on the git commit message. See the documentation of
+<a href="codingconventions.html#ChangeLogs">ChangeLog format</a>.</li>
<li>Make sure to rebuild any generated files that would be affected by
the patch. Make sure to check them in along with the files explicitly
@@ -347,30 +347,6 @@ accordingly. It may be easier to cherry-pick some smaller changes onto master
don't need to <code>merge --squash</code> squash, but still need to make sure
the commits on the branch satisfy the above rules for commits.
-<hr />
-<h2 id="changelog">git-merge-changelog</h2>
-
-git's native handling of ChangeLog merges is pretty bad, but there's a separate
-git-merge-changelog tool that improves things dramatically. Some operating
-system distributions have a git-merge-changelog package already, or to build it
-by hand you can do
-
-<blockquote><pre>
-git clone git://git.savannah.gnu.org/gnulib.git
-cd gnulib
-./gnulib-tool --create-testdir --dir=/tmp/testdir123 git-merge-changelog
-cd /tmp/testdir123
-./configure
-make
-make install
-</pre></blockquote>
-And then to enable it, do
-<blockquote><pre>
-git config --global merge.merge-changelog.name "GNU-style ChangeLog merge driver"
-git config --global merge.merge-changelog.driver "git-merge-changelog %O %A %B"
-echo "ChangeLog* merge=merge-changelog" >> $GCCSRCDIR/.git/info/attributes
-</pre></blockquote>
-
<hr />
<h2 id="vendor">Personal and vendor branches</h2>
@@ -457,6 +433,7 @@ repository:</p>
</li>
<li><i>gcc-descr</i> - Undocumented</li>
<li><i>gcc-undescr</i> - Undocumented</li>
+ <li><i>gcc-verify</i> - Undocumented</li>
</ul>
<p>The final customization that the script makes is to add a diff rule so
