Read-write CVS access

We have read/write access to the CVS repository available for all our significant developers. Maintainers are also encouraged to edit the GNATS database.


Contents

  1. Authenticated access
  2. Setting up your local CVS tree
  3. Write access policies
  4. Checking in a change
  5. Example check-in session

Authenticated access

Authenticated access is provided via the SSH protocol. Please provide us with your public key which you can generate via the "ssh-keygen" program. This will store your public key in the file .ssh/identity.pub in your home directory. We need the entire contents of that file. You should mail it directly to law@cygnus.com. Yes, we realize it's a public key, but there's no sense in cluttering up the developers list with keys.

Once we have this information we will set up an account on gcc.gnu.org and inform you by mail. At this point you should be able to check out a tree with CVS and add yourself to the MAINTAINERS file to test write access. See Checking in a change for how to proceed with checking in your changes.


Setting up your local CVS tree

Once you can login to the machine, it's trivial to start using ssh from your remote machine. Set CVS_RSH in your environment to "ssh". Then issue the command

cvs -z 9 -d :ext:username@gcc.gnu.org:/cvs/gcc co gcc
where username is your user name at gcc.gnu.org. This will check out a new CVS tree that you should be able to work with in the normal fashion, including committing changes.

It is also possible to convert an existing CVS tree to use ssh by replacing all the "Root" files in the local tree with the following contents:

username@gcc.gnu.org:/cvs/gcc

To avoid the nuisance of having to supply your passphrase for each operation, you may want to use ssh-agent(1) followed by ssh-add(1) and entering your passphrase once for all. Either start your session as a child of ssh-agent or run it as a demon and set the values of the environment variables SSH_AUTHENTICATION_SOCKET and SSH_AGENT_PID in each relevant process to what ssh-agent prints when it starts. To avoid messages about (lack of) X11 forwarding, put in your $HOME/.ssh/config and entry like:

Host gcc.gnu.org
ForwardX11 no

Web pages

Note that when you check in changes to our web pages, these will automatically be checked out into the web server's data area.


Write access policies

The GCC project grants some developers various levels of write access to the GCC master sources. CVS doesn't provide fine grained control over access to the repository; therefore, we depend on each developer to follow the appropriate policies.

Global write permission.
A very limited number of developers have global write permission over the entire repository.
Localized write permission.
This is for people who have primary responsibility for ports, front ends, or significant hunks of code in the compiler. These folks are allowed to make changes in code they maintain without going through any kind of approval process.
Write after approval.
This is folks that make regular contributions, but do not fall into one of the two 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 into the GCC sources.

The list of folks with write access to the repository can be found in the MAINTAINERS file in the GCC distribution.

Also note that fixes for obvious typos in ChangeLog files, docs, web pages, comments and similar stuff need not be approved. Just check in the fix. We don't want to get overly anal about checkin policies.

When you have checked in a patch exactly as it has been approved, you do not no need to tell that to people -- including the approver. People interested in when a particular patch is committed can check CVS or the gcc-cvs list.

Maintainers are free to import files maintained outside the tree from their official versions without explicit write approval. Such files would include config.guess and config.sub.


Checking in a change

It is expected that before you check in any change you will do the following:

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.

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 CVS manual but instead a supplement. The CVS manual is distributed as part of the CVS sources as a texinfo file. http://www.cvshome.org/cyclic/cvs/doc-blandy.html contains a link to an reasonably simple introduction to CVS.

In all the commands listed below, you can give an explicit list of filenames to the cvs command. We recommend you list files explicitly when performing checkins to avoid accidental checkins of local code.

  1. Sync your sources with the master repository via "cvs update" before attempting a checkin; this will save you a little time if someone else has modified that file since the last time you sync'd your sources. It will also identify any files in your local tree that you have modified.
  2. 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.
  3. 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.
  4. We recommend using "cvs diff" 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.
  5. Use "cvs commit" to check in the patch. You can enter the log message via the "-m" argument to commit, or wait for the editor window to appear and enter the log message in the editor window.
  6. After exiting the editor, CVS will connect to the GCC cvs server and check in your changes. When your prompt returns the checkin is finished. A message will be sent to the "gcc-cvs" mailing list (when set up) indicating that a change was made. CVS will provide a message if an error occurs and it will not check in any files.

Example check-in session

Here's an actual check-in session for a patch John Carr recently sent to the GCC list. This was the ChangeLog for his change:

Sun Feb  8 08:02:13 1998  John Carr  <jfc@mit.edu>

   * bitmap.c (bitmap_debug_file): HOST_PTR_PRINTF converts a pointer,
   not a HOST_WIDE_INT.

   * calls.c (expand_call): Change test of expand_inline_function
   return value to stop compiler warning.

   * genattrtab.c (RTL_HASH): Cast pointer to long, not HOST_WIDE_INT.

First, I sync my local repository.

[/law/gcc] cvs update
? libobjc
? gcc/.ada
? gcc/jump.c.SAVE
? gcc/loop.c.SAVE
M MAINTAINERS
M Makefile.in
M gcc/loop.c
M gcc/cp/parse.c
M gcc/objc/Make-lang.in
M gcc/objc/Makefile.in

The question marks indicate files in my local repository that are not part of the official sources. The "M" indicates files I've changed locally for some unrelated work -- thus I have to be careful to avoid checking them in. A "U" would have indicated a file that CVS updated because my local copy was out of date relative to the master sources.

The local repository is now up to date.

Apply the patch to the local source

[/law/gcc/gcc] patch < ~/Mail/gcc/pendingpatches/42 
Hmm...  Looks like a new-style context diff to me...
The text leading up to this was:
[ uninteresting text deleted ]
|*** bitmap.c.egcs      Sat Dec 20 06:31:11 1997
|--- bitmap.c   Sun Feb  8 08:01:32 1998
--------------------------
Patching file bitmap.c using Plan A...
Hunk #1 succeeded at 563.
Hunk #2 succeeded at 573.
Hmm...  The next patch looks like a new-style context diff to me...
The text leading up to this was:
--------------------------
|*** calls.c.egcs       Sun Feb  8 07:44:02 1998
|--- calls.c    Sun Feb  8 08:00:08 1998
--------------------------
Patching file calls.c using Plan A...
Hunk #1 succeeded at 730.
Hmm...  The next patch looks like a new-style context diff to me...
The text leading up to this was:
--------------------------
|*** genattrtab.c.egcs  Sun Feb  8 07:44:04 1998
|--- genattrtab.c       Sun Feb  8 08:05:36 1998
--------------------------
Patching file genattrtab.c using Plan A...
Hunk #1 succeeded at 506.
done

Add ChangeLog entry by hand

ChangeLog entries should be handled as straight text; patches against ChangeLogs rarely apply correctly.

[/law/gcc/gcc] vi ChangeLog

Review changes for correctness

The patch and its associated ChangeLog entry are in my local tree; now I run cvs diff on the modified files and review the output.

[/law/gcc/gcc] cvs diff -c3p bitmap.c calls.c genattrtab.c > /tmp/FOO

Look at /tmp/FOO and verify that only the changes we want are in the diff file.

Update Copyrights

Review the changed files to see if any copyrights need updating, in this particular case all three needed their copyrights updated.

[/law/gcc/gcc] vi bitmap.c calls.c genattrtab.c

Commit the changes to the central repository

[/law/gcc/gcc] cvs commit ChangeLog bitmap.c calls.c genattrtab.c

My editor starts and I enter the log message; the lines starting with CVS: are automatically added by CVS and will be automatically removed:

        * bitmap.c (bitmap_debug_file): HOST_PTR_PRINTF converts a pointer,
        not a HOST_WIDE_INT.

        * calls.c (expand_call): Change test of expand_inline_function
        return value to stop compiler warning.

        * genattrtab.c (RTL_HASH): Cast pointer to long, not HOST_WIDE_INT.

CVS: ----------------------------------------------------------------------
CVS: Enter Log.  Lines beginning with `CVS:' are removed automatically
CVS:
CVS: Committing in .
CVS:
CVS: Modified Files:
CVS:    ChangeLog bitmap.c calls.c genattrtab.c
CVS: ----------------------------------------------------------------------

Now write & quit from the editor, and CVS will start the actual checkin process....

Checking in ChangeLog;
/cvs/gcc/./gcc/ChangeLog,v  <--  ChangeLog
new revision: 1.746; previous revision: 1.745
done
Checking in bitmap.c;
/cvs/gcc/./gcc/bitmap.c,v  <--  bitmap.c
new revision: 1.6; previous revision: 1.5
done
Checking in calls.c;
/cvs/gcc/./gcc/calls.c,v  <--  calls.c
new revision: 1.12; previous revision: 1.11
done
Checking in genattrtab.c;
/cvs/gcc/./gcc/genattrtab.c,v  <--  genattrtab.c
new revision: 1.15; previous revision: 1.14
done
[/law/gcc/gcc] 

Note that only a single CVS log message was used for all the files; this is the normal and expected behavior. It is not necessary to perform multiple commits and split up the CVS log entry on a file by file basis. Note this implies that each checkin is for a single logical change that may effect multiple files. If you have several unrelated changes, you should check them in with separate cvs commit commands.

And that's it!