public inbox for gcc-cvs-wwwdocs@sourceware.org
help / color / mirror / Atom feed
* gcc-wwwdocs branch master updated. 6136760e5ad2d1221f659d708cc220ebd4849590
@ 2020-01-10 18:02 jsm28
0 siblings, 0 replies; only message in thread
From: jsm28 @ 2020-01-10 18:02 UTC (permalink / raw)
To: gcc-cvs-wwwdocs
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 6136760e5ad2d1221f659d708cc220ebd4849590 (commit)
from 051594a2c66870dd65129e38b845e94da65b7a0c (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 6136760e5ad2d1221f659d708cc220ebd4849590
Author: Joseph Myers <joseph@codesourcery.com>
Date: Fri Jan 10 18:01:36 2020 +0000
Add rough documentation of using git with GCC.
This is very preliminary documentation based on the corresponding SVN
documentation. It is deliberately not linked to from anywhere, and
does not yet include the list of branches from svn.html (which is very
out of date regarding what branches are actually active).
diff --git a/htdocs/git.html b/htdocs/git.html
new file mode 100644
index 0000000..0166ff7
--- /dev/null
+++ b/htdocs/git.html
@@ -0,0 +1,167 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<meta name="description" content="Anonymous read-only access to the GCC project Git source repository." />
+<meta name="keywords" content="Git, version control, GCC, source, public, repository" />
+<title>GCC: Anonymous read-only Git access</title>
+<link rel="stylesheet" type="text/css" href="https://gcc.gnu.org/gcc.css" />
+</head>
+
+<!-- GCC maintainers, please do not hesitate to update/contribute entries
+ concerning branches you maintain! 2005-08-29, Gerald.
+-->
+
+<body>
+<h1>GCC: Anonymous read-only Git access</h1>
+
+<p><strong>The conversion from SVN to Git is in progress. The
+repository described here may not yet be the final version of that
+conversion.</strong></p>
+
+<p>Our Git source repository is available read-only to the public at
+large. That way you can pick up any version (including releases) of
+GCC that is in our repository.</p>
+
+<p>In addition you
+can <a href="https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git">browse our
+Git history online</a>.</p>
+
+<p>(Our <a href="about.html#git">web pages are managed via Git in a
+separate repository</a>.)</p>
+
+
+<h2>Using the Git repository</h2>
+
+<p>Assuming you have
+<a href="https://git-scm.com/">Git</a> installed, you can
+check out the GCC sources using the following command:</p>
+
+<blockquote><p>
+<code>git clone git://gcc.gnu.org/git/gcc.git SomeLocalDir</code>
+</p></blockquote>
+
+<p>If you are behind a firewall that does not allow the git protocol
+through, you can replace <code>git://</code> with <code>http://</code>.
+You should only use the http protocol if
+the git protocol does not work; the http protocol has a higher server
+overhead associated with it and will be slower.</p>
+
+<!-- Comment out till savannah gets back to us (see above)
+<p>In case of problems with the repository at savannah.gnu.org please
+contact savannah-hackers@gnu.org.</p> -->
+
+
+<h3 id="generated_files">Generated files</h3>
+
+<p>Our source tree contains a number of files that are generated
+from other source files by build tools such as Bison, Autoconf, and
+Gperf. Bison is now required when using Git to access our sources,
+but all other generated files are included in the source tree so that
+GCC can be built without these build tools. The Git checkout and
+update operations do not insure that the timestamps of generated files
+are later than those of the files they are generated from. The script
+<code>contrib/gcc_update</code> updates the timestamps for all these
+generated files. See the comments in that script for instructions on
+running it.</p>
+
+<p>GCC's build system (in particular Make) uses file timestamps to
+determine if a generated file needs to be updated by running a particular
+build tool. Because of this, GCC's build system may believe that
+a generated file needs regenerating even though its source has not
+changed, and require a particular build tool to rebuild that generated
+file. If the appropriate build tool is installed on your system, then
+this will not be a problem. If you do not intend to make changes to
+the source, you can avoid installing these build tools by running
+<code>contrib/gcc_update</code>.</p>
+
+<p>There has been some discussion of removing these generated files
+from GCC's Git source tree (there is no discussion of removing them
+from the released source tarballs). If that happens then
+building GCC from the Git source tree would require installing
+the above mentioned build tools. Installing these build tools is not
+particularly difficult, but can be time consuming especially if you
+only occasionally install GCC on a particular system.</p>
+
+<p>The build tools that GCC uses are all available from the GNU
+Project (see <a href="https://www.gnu.org">https://www.gnu.org</a>),
+are often already available on many systems, and can often be found
+already built for some systems. A partial list of these build tools
+is: Autoconf, Bison, Xgettext, Automake, and Gperf.</p>
+
+<h3>Conflicts when using <code>git pull</code></h3>
+
+<p>It is not uncommon to get Git conflict messages for some generated files
+when updating your local sources from the Git repository. Typically such
+conflicts occur with autoconf generated files.</p>
+
+<p>As long as you haven't been making modifications to the generated files
+or the generator files, it is safe to revert the local differences
+using <code>git checkout</code> on the affected files, then run
+<code>git pull</code> again.</p>
+
+
+<h2 id="tags">Branches and Tags</h2>
+
+<p>A branch called <em>branchname</em> can be checked out with the
+following command:</p>
+
+<blockquote><p>
+<code>git clone -b <em>branchname</em> git://gcc.gnu.org/git/gcc.git gcc</code>
+</p></blockquote>
+
+<p>(The release branch of the GCC <em>SERIES</em> release series
+is named <code>releases/gcc-<em>SERIES</em></code>.)</p>
+
+<p>Similarly a tag called <em>tagname</em> can be checked out with the
+following command:</p>
+
+<blockquote><p>
+<code>git clone -b <em>tagname</em> git://gcc.gnu.org/git/gcc.git gcc</code>
+</p></blockquote>
+
+<p>(The Git tag for GCC <i>X</i>.<i>Y</i>.<i>Z</i> is of the form
+<code>releases/gcc-<em>X</em>.<em>Y</em>.<em>Z</em></code>. Under the
+release numbering scheme used for GCC 5 and later release
+series, <em>Y</em> is always nonzero and <em>Z</em> is always zero for
+a release, with other version numbers being used for development
+versions.)</p>
+
+<p>The following list provides some representative examples:</p>
+
+<ul>
+ <li>releases/gcc-9 (a branch)</li>
+ <li>releases/gcc-8 (a branch)</li>
+ <li>releases/gcc-7.5.0 (a tag)</li>
+ <li>releases/gcc-4.9 (a branch)</li>
+ <li>releases/gcc-4.9.0 (a tag)</li>
+</ul>
+
+<p>To get a list of available branches, after checking out any branch,
+use the command:</p>
+<blockquote>
+<p>
+<code>git branch -a</code>
+</p>
+</blockquote>
+
+<p>Similarly, to list tags:</p>
+<blockquote>
+<p>
+<code>git tag -l</code>
+</p>
+</blockquote>
+
+<p>To view logs for a branch only up to the point at which it was
+created, use the command <code>git log origin/<em>branchname</em>
+^origin/<em>parentbranchname</em></code>; for example:
+
+<blockquote>
+<p>
+<code>git log origin/releases/gcc-9 ^origin/master</code>
+</p>
+</blockquote>
+
+</body>
+</html>
diff --git a/htdocs/gitwrite.html b/htdocs/gitwrite.html
new file mode 100644
index 0000000..f53b583
--- /dev/null
+++ b/htdocs/gitwrite.html
@@ -0,0 +1,308 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Read-write Git access</title>
+<link rel="stylesheet" type="text/css" href="https://gcc.gnu.org/gcc.css" />
+</head>
+
+<body>
+
+<h1>Read-write Git access</h1>
+
+<p><strong>The conversion from SVN to Git is in progress. The
+repository described here may not yet be the final version of that
+conversion.</strong></p>
+
+<p>We have read/write access to the Git repository available for
+maintainers and significant developers.</p>
+
+<p>Our <a href="about.html#git">web pages are managed via git</a>.</p>
+
+<hr />
+<h2>Contents</h2>
+<ol>
+ <li><a href="#authenticated">Authenticated access</a></li>
+ <li><a href="#setup">Setting up your local Git tree</a></li>
+ <li><a href="#policies">Write access policies</a></li>
+ <li><a href="#testing">Testing changes</a></li>
+ <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="#account">Tips&Tricks around your account</a></li>
+</ol>
+
+<hr />
+<h2 id="authenticated">Authenticated access</h2>
+
+<p>We provide authenticated access via the SSH protocol. This needs to
+be sponsored by an existing maintainer (someone with "write after approval"
+is not sufficient).</p>
+
+<p>If you already have an account on sourceware.org / gcc.gnu.org, ask
+<code>overseers@gcc.gnu.org</code> to add access to the GCC repository.
+Include the name of your sponsor and CC: her.
+If you do not have an account yet, use <a
+href="https://sourceware.org/cgi-bin/pdw/ps_form.cgi">this form</a>,
+again specifying your sponsor.</p>
+
+<p>We will then provision you on
+<code>gcc.gnu.org</code> and inform you by mail. At this point,
+check out a tree using the instructions below and add yourself
+to the MAINTAINERS file. Note: Your first and last names <em>must</em>
+be exactly the same between your account on gcc.gnu.org and the
+MAINTAINERS file. Place your name in the correct section following
+the conventions specified in the file (e.g. "Write After Approval"
+is "last name alphabetical order").</p>
+
+<p>Then produce a diff to that file and circulate it to the
+<code>gcc-patches</code> list, whilst also checking in your change to
+test write access (approval from the mailing list is not needed in this
+one case). For all other changes, please be sure to follow the write
+access policies below.</p>
+
+<hr />
+<h2 id="setup">Setting up your local Git tree</h2>
+
+<p>Once your account has been set up, check out the GCC sources by
+issuing the command:</p>
+
+<blockquote><p><code>
+git clone git+ssh://<i>username</i>@gcc.gnu.org/git/gcc.git gcc
+</code></p></blockquote>
+
+<p>where <i>username</i> is your user name at gcc.gnu.org.</p>
+
+<p>It is also possible to convert an existing Git tree to use SSH by
+using <code>git config</code>:</p>
+
+<blockquote><p><code>
+git config --set remote.origin.url git+ssh://<i>username</i>@gcc.gnu.org/git/gcc.git
+</code></p></blockquote>
+
+<p>To avoid the nuisance of having to supply your passphrase for each
+operation, you may want to use <code>ssh-agent</code>(1) and
+<code>ssh-add</code>(1).</p>
+
+<p>To avoid messages about (lack of) X11 forwarding, put in your
+<samp>$HOME/.ssh/config</samp> an entry like:</p>
+
+<blockquote><p><code>
+Host gcc.gnu.org<br />
+ForwardX11 no
+</code></p></blockquote>
+
+<hr />
+<h2 id="policies">Write access policies</h2>
+
+<p>The GCC project grants developers various levels of write access to
+and review authority over the GCC master sources. We have not put any
+technical enforcement in place, rather we rely on everyone to follow
+the appropriate policies.</p>
+
+<dl>
+ <dt>Global reviewers.</dt>
+ <dd><p>A limited number of developers have global review permission
+ and can approve other people's changes to any part of the compiler.
+ </p></dd>
+
+ <dt>Localized write permission.</dt>
+ <dd><p>This is for people who have primary responsibility for ports,
+ front ends, or other specific aspects of the compiler. These folks
+ are allowed to make changes to areas they maintain and related
+ documentation, web pages, and test cases (and target conditionals)
+ without approval from anyone else, and approve other people's changes
+ in those areas.
+ They must get approval for changes elsewhere in the compiler.</p>
+
+ <p>Maintainers of a port maintain the relevant files in
+ <code>gcc/config</code>, documentation, web pages, and test cases
+ and aspects of these relevant to that port. Port maintainers do
+ not have approval rights beyond this.</p></dd>
+
+ <dt>Localized review permission.</dt>
+ <dd><p>This is similar to localized write permission, except
+ that reviewers required approval for their own changes.</p></dd>
+
+ <dt>Write after approval.</dt>
+ <dd><p>This is folks that make regular contributions, but do not
+ fall into one of the previous categories. People with write
+ after approval need to submit their patches to the list; once the
+ patches have been approved by the appropriate maintainers the
+ patches may be checked in. The steering committee
+ or a well-established GCC maintainer (including reviewers) can
+ <a href="#authenticated">approve for write access</a> any person
+ with GNU copyright assignment papers in place and known to submit
+ good patches.</p></dd>
+</dl>
+
+<p>The list of folks with write access to the repository can be found
+in the MAINTAINERS file in the GCC distribution.</p>
+
+<p>When you have checked in a patch exactly as it has been approved,
+you do not need to tell that to people -- including the approver.
+People interested in when a particular patch is committed can check
+Git or the <a href="https://gcc.gnu.org/ml/gcc-cvs/">gcc-cvs</a>
+list.</p>
+
+<h3 id="all">Free for all</h3>
+
+<p>The following changes can be made by everyone with write access:</p>
+
+<p>Obvious fixes can be committed without prior approval. Just check
+in the fix and copy it to <code>gcc-patches</code>. A good test to
+determine whether a fix is obvious: <q>will the person who objects to
+my work the most be able to find a fault with my fix?</q> If the fix
+is later found to be faulty, it can always be rolled back. We don't
+want to get overly restrictive about checkin policies.</p>
+
+<p>Similarly, no outside approval is needed to revert a patch that you
+checked in.</p>
+
+<p><a href="codingconventions.html#upstream">Importing files maintained
+outside the tree from their official versions</a>.</p>
+
+<p><a href="#branches">Creating and using a branch</a> for development,
+including outside the parts of the compiler one maintains, provided that
+changes on the branch have copyright assignments on file. Merging such
+developments back to the mainline still needs approval in the usual way.</p>
+
+
+<hr />
+<h2 id="testing">Testing changes</h2>
+
+<p>All changes must be tested according to the
+<a href="contribute.html#testing">instructions for testing patches</a>
+before they are checked in. If you wrote the patch yourself, you
+should test it yourself, unless there is a reason why someone else
+must do it for you (for instance, if you are fixing a problem on a
+system you do not have access to). If you are checking in a patch for
+someone else, you only need to test it if they did not.</p>
+
+<p>You must test exactly the change you intend to check in; it is not
+good enough to have tested an earlier variant. (Unless the only
+changes from the earlier variant are formatting and comment changes;
+if there are <strong>any</strong> changes to the code itself you
+should re-bootstrap.) It is a good idea to re-test patches which were
+submitted a long time ago before applying them, even if nothing
+appears to have changed.</p>
+
+<p>When you post your change to <code>gcc-patches</code>, state the
+canonical name(s) of the platform(s) you used for testing.</p>
+
+<p>These rules are designed to ensure that checked-in code does not
+contain bugs that prevent other people from continuing to get their
+work done. There will always be bugs, but these rules help to
+minimize the amount of time where the tree does not build at
+all. Repeated failure to adhere to these rules could result in the
+revocation of check-in privileges by the Steering Committee.</p>
+
+<hr />
+<h2 id="checkin">Checking in a change</h2>
+
+<p>The following is meant to provide a very quick overview of how to
+check in a change. It is not meant to be a replacement for the Git
+documentation but instead a supplement. The Git documentation is
+available both as part of the Git source distribution, as well as
+<a href="https://git-scm.com/doc">on the Git website</a>.</p>
+
+<p>In all the commands listed below, you can give an explicit list of
+filenames to the git command. We recommend you list files explicitly
+when performing checkins to avoid accidental checkins of local
+code.</p>
+
+<p>We prefer that each checkin be of a complete, single logical
+change, which may affect multiple files. The log message for that
+checkin should be the complete ChangeLog entry for the change. This
+makes it easier to correlate changes across files, and minimizes the
+time the repository is inconsistent. If you have several unrelated
+changes, you should check them in separately.</p>
+
+<ol>
+<li>Sync your sources with the master repository via "<code>git
+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>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
+modified by the patch.</li>
+
+<li>If the patch adds any new files, such as testcases, use <code>git
+add</code> to make Git aware of them.</li>
+
+<li>We recommend using "<code>git diff HEAD</code>" after applying a
+patch to a local tree. Review the output to make sure that only the
+changes you wanted to check in will be checked in. Also check to see
+if the copyright dates need to be updated.</li>
+
+<li>Use "<code>git commit</code>" to check in the patch; either name
+the files to commit explicitly on the command line, or use <code>git
+commit -a</code> to commit all modified files in the source tree (it
+is still necessary to use <code>git add</code> first for any new
+files). <strong>If committing a patch for someone else,
+use <code>--author "<em>Author Name</em>
+<<em>Author@Email.Address</em>>"</code> to credit the patch to
+its author.</strong> You can enter the log message via the
+"<code>-m</code>" argument to commit, or wait for the editor window to
+appear and enter the log message in the editor window. <strong>If you
+use <code>git commit</code> without <code>-a</code>, and without
+naming files explicitly, it will only commit files explicitly added
+with <code>git add</code>, and will ignore any changes to those files
+made after you called <code>git add</code> for them.</strong></li>
+
+<li>After exiting the editor, Git will check in your
+changes <strong>locally</strong>. When your prompt returns
+the <strong>local</strong> checkin is finished, but you still need to
+push the changes to the shared repository; do <code>git push</code>.
+A message will be sent to the gcc-cvs mailing list indicating that a
+change was made. If <code>git push</code> gives an error because
+someone else has pushed their own changes to the same branch,
+do <code>git pull --rebase</code> before trying <code>git push</code>
+again.</li>
+
+<hr />
+<h2 id="branches">Creating and using branches</h2>
+
+<p>To create a branch for development, you can use <code>git
+push</code> as follows:</p>
+
+<blockquote><pre>
+git push origin master:devel/$BRANCH
+</pre></blockquote>
+
+<p>Also, please document such branches at the
+<a href="git.html#devbranches">list of development branches</a>.
+</p>
+
+<p>When merging changes from mainline (or another branch) to a branch,
+do not copy the entire set of ChangeLog entries. Just use something
+like "Merge from mainline" or similar.</p>
+
+<hr />
+<h2 id="account">Tips&Tricks around your account</h2>
+
+<p>Your gcc.gnu.org account also receives e-mail (and is what you
+use for Bugzilla). If you ever need to change the address e-mail to
+<i>username</i>@gcc.gnu.org is forwarded to, you can easily
+do so using</p>
+<blockquote><pre>
+ssh <i>username</i>@gcc.gnu.org email mynewaddress@example.com
+</pre></blockquote>
+
+<p>Similarly if you want to add a new SSH key to your account:</p>
+<blockquote><pre>
+ssh <i>username</i>@gcc.gnu.org appendkey < KEYFILE
+</pre></blockquote>
+
+<p>Or replace all your SSH keys:</p>
+<blockquote><pre>
+ssh <i>username</i>@gcc.gnu.org replacekey < KEYFILE
+</pre></blockquote>
+
+</body>
+</html>
-----------------------------------------------------------------------
Summary of changes:
htdocs/git.html | 167 ++++++++++++++++++++++
htdocs/{svnwrite.html => gitwrite.html} | 242 ++++++++------------------------
2 files changed, 226 insertions(+), 183 deletions(-)
create mode 100644 htdocs/git.html
copy htdocs/{svnwrite.html => gitwrite.html} (59%)
hooks/post-receive
--
gcc-wwwdocs
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2020-01-10 18:02 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-01-10 18:02 gcc-wwwdocs branch master updated. 6136760e5ad2d1221f659d708cc220ebd4849590 jsm28
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).