public inbox for gcc-cvs-wwwdocs@sourceware.org
help / color / mirror / Atom feed
* gcc-wwwdocs branch master updated. 1498f1d49b73c4ce3ffb1c886a4b70daa51cf66c
@ 2020-05-19 7:24 Martin Liska
0 siblings, 0 replies; only message in thread
From: Martin Liska @ 2020-05-19 7:24 UTC (permalink / raw)
To: gcc-cvs-wwwdocs
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 12353 bytes --]
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gcc-wwwdocs".
The branch, master has been updated
via 1498f1d49b73c4ce3ffb1c886a4b70daa51cf66c (commit)
from 3cda2493a87ce15b079f8013d2cf096cd4d9c585 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 1498f1d49b73c4ce3ffb1c886a4b70daa51cf66c
Author: Martin Liska <mliska@suse.cz>
Date: Tue May 19 09:21:47 2020 +0200
Update changed relates to gcc-changelog format.
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␣␣<mliska@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␣␣<mliska@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 <john@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 <jack@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
-----------------------------------------------------------------------
Summary of changes:
htdocs/codingconventions.html | 110 ++++++++++++++++++++++++++++++++++++------
htdocs/contribute.html | 16 +-----
htdocs/gitwrite.html | 33 ++-----------
3 files changed, 102 insertions(+), 57 deletions(-)
hooks/post-receive
--
gcc-wwwdocs
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2020-05-19 7:24 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-05-19 7:24 gcc-wwwdocs branch master updated. 1498f1d49b73c4ce3ffb1c886a4b70daa51cf66c Martin Liska
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).