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.
- git_update_version.py - a replacement of
maintainer-scripts/update_version_git which
bumps DATESTAMP and generates ChangeLog entries (for now into ChangeLog.test
files)
Where does this check things out? (The existing ~gccadmin/gcc-checkout
isn't suitable for that, it needs to stay on master to have the correct
version of maintainer-scripts rather than being switched to other
branches, though I suppose a second long-lived checkout that gets updated
automatically could be used. If you check things out somewhere else
temporarily, it's important to be sure the checkout gets deleted
afterwards rather than having multiple checkouts accumulating. That's
especially the case if you use a checkout in /tmp as a single GCC
repository clone / checkout uses a significant proportion of the free
space on the root filesystem; /sourceware/snapshot-tmp/gcc has more free
space for large temporary directories.)
Well, we can make a proper git clone of the original repository that will
be used for the daily bumps. I bet we'll have a place for one more clone?
The second part is git hook that will reject all commits for release and
master branches.
that violate ChangeLog format. Right now, strict mode is disabled in the
hooks.
Note that the present state of having GCC-specific patches to the git
hooks is supposed to be a temporary one; we want to move to all relevant
GCC-specific configuration being in refs/meta/config rather than custom
code, so GCC and sourceware can share a single instance of the hooks which
in turn can use the same code as in the upstream AdaCore repository, so
that future updates of the hooks from upstream are easier. See the issues
I filed at https://github.com/AdaCore/git-hooks/issues for the existing
custom GCC changes and the pull request
https://github.com/AdaCore/git-hooks/pull/12 to bring in implementations
of many of those features (not sure if it covers everything or not). So
it's important to consider how these checks could be implemented without
needing GCC-specific code directly in these hooks (for example, using the
new hooks.update-hook mechanism added by one of the commits in that pull
request, or getting extra features added to the upstream hooks in a
generic form if necessary).
I welcome the attempt to unify the hooks with AdaCore upstream. I believe this
should not block gcc-changelog attempt now. Later on, we can add it to
hooks.update-hook mechanism.
Thanks,
Martin
diff --git a/htdocs/codingconventions.html b/htdocs/codingconventions.html
index f4732ef6..ffa6db32 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">author_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">author_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 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
+
+$author_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
