Table of Contents

W3C CVS For Dummies

2010-234 Tantek Çelik - originally drafted (with incremental updates since, e.g. 2011-081)

<html><div style=“width:50%;float:left”></html>

The CSSWG has shifted to Mercurial for specs. This page is being kept here in case it is useful for other projects.

<html></div></html>

Introduction

Setting up CVS and specifically, W3C's setup for CVS is quite challenging, obtuse, and painful.

Having failed to do this by myself, I took reasonably thorough notes while @fantasai and @davidbaron helped walk me through this setup, including trouble-shooting several problems I encountered along the way.

It is my hope that documenting the steps I had to take will help others get setup with CVS and editing W3C specs much more quickly and efficiently, and perhaps, in the long run, the process for editing W3C specifications can be made more efficient.

Tantek Çelik, 2010-236

Public Web Access to W3C CVS

If all you want to do is browse through W3C's CVS repository on the web, you can start here:

http://dev.w3.org/cvsweb/

However, if you want to actually *check out* W3C's CVS repository (with the intent to make changes), the instructions/info on that page is a bit too cryptic for most folks.

That's why this document is here.

Make Sure You Have

Before you get started with the setup steps, you need:

  1. your W3C username - you need this for communicating with the W3C's CVS server
  2. your public key - you need to setup SSH keys for yourself.

Send your public key file (id_dsa.pub) to Bert Bos. Until your public key file has been setup on the CVS server you will not be able to connect successfully using ssh.

Step 0 - Install CVS

You need to first install CVS on your system.

If you have a Mac:

The MacPorts installer will run a program to determine if it can be installed.

If you get an error alert like:

<html><pre> +—————————————————-+

MacPorts-2.0.3 can't be installed on this
computer.
Xcode is not installed, or was installed with UNIX
Development (10.5+) or Command Line Support
(10.4) deselected.
1)

+—————————————————-+ </pre></html>

Then go back and make sure you've installed Xcode - you should have a “Developer” folder on your internal drive.

If you don't have a “Developer” folder on your internal drive, you probably haven't successfully installed Xcode.

If you have installed Xcode, make sure you've updated it to the latest version. You may need to check the Xcode page in the Apple Mac App store - if you see a button to “Update” or “Upgrade”, click it.

Now retry installing MacPorts again.

sudo port install cvs

If you get an error message like:

sudo: port: command not found

Then open a *new* Terminal window and try the command again:

sudo port install cvs

You will be asked for your “Password:” - enter it.

You should then see a bunch of messages like:

--->  Fetching cvs
--->  Attempting to fetch cvs-1.11.23.tar.bz2 from http://distfiles.macports.org/cvs
--->  Verifying checksum(s) for cvs
--->  Extracting cvs
--->  Configuring cvs
--->  Building cvs
--->  Staging cvs into destroot
--->  Installing cvs @1.11.23_0
--->  Activating cvs @1.11.23_0
--->  Cleaning cvs

Congratulations, you've installed the command-line cvs tool on your Mac.

For other platforms … tips forthcoming.

Step 1 - Setup CVS_RSH

W3C requires you to use SSH to connect to their CVS server.

What does this mean? It means W3C only allows secure access to the CVS server - and thus you must setup SSH on your machine to act as the conduit for CVS.

The short version, type this into a terminal window (e.g. in the Terminal application on MacOSX)

export CVS_RSH=ssh

Now test that you did the right thing by typing in:

echo $CVS_RSH

You should see a message like:

ssh

followed immediately by a prompt.

You'll want to set that up to happen automatically for you.

The general solution is to add the above export command to your .bash_profile.

Alternatively on some systems you can set the preference via a system preferences:

Here is a command to add the above export command to your .bash_profile for you (which automatically creates a .bash_profile for you if you don't have one already, otherwise appends the command to the end).

echo "export CVS_RSH=ssh" | cat >> .bash_profile

You'll need to close your Terminal window and open a new one for it to take effect.

Here is another reference for setting up CVS to use SSH (though in practice I haven't found that I need it, and the instructions there seem cryptic too)

Step 2 - How To Do Secure Checkouts

How to do secure checkouts that allow you to check in.

You should have something like:

:ext:Tantekelik@dev.w3.org:/sources/public

But with YOUR username instead of “Tantekelik” (used only as a placeholder in these examples)

Note that your W3C username is CASE-SENSITIVE, be sure to enter it precisely.

cvs -d :ext:Tantekelik@dev.w3.org:/sources/public co csswg

You might see a message like:

The authenticity of host 'dev.w3.org (128.30.52.19)' can't be established.
RSA key fingerprint is fb:30:ab:09:1c:b3:1a:74:93:67:57:fd:69:16:0b:97.

That's the right one. If you get a different fingerprint back you're being hacked.

Then when asked:

Are you sure you want to continue connecting (yes/no)?

Answer:

yes

Then you'll likely get a warning like:

Warning: Permanently added 'dev.w3.org,128.30.52.19' (RSA) to the list of known hosts.

IF you get an error message like

Permission denied (publickey).

FIRST check to make sure you typed in your username *case-sensitively* including proper capitals if any.

THEN if it still doesn't work, something is wrong with your public key setup. Email Bert Bos and ask him for help making sure your public key is setup correctly with W3C.

On Mac OS X (10.6) Terminal, you should get an alert dialog box that says:

<html><pre> +———————————————–+

Enter your password for the SSH key “id_dsa”.
Password:
(Cancel) 2)

+———————————————–+ </pre></html>

Enter your SSH pass phrase that you used when you created the key and click OK.

On other OS's (or terminal/shell applications), you'll be prompted in some other way for pass phrase for your SSH key. Feel free to edit this and add OS-specific experiences/screenshots.

You may get a message like:

Identity added: /Users/USERNAME/.ssh/id_dsa (/Users/USERNAME/.ssh/id_dsa)

where USERNAME is your login alias for your client box.

IF you get an error message like:

Connection closed by 128.30.52.19
cvs [checkout aborted]: end of file from server (consult above messages if any)

THEN it could be a number of things. E.g.

You SHOULD see a message like:

cvs.bin checkout: Updating csswg

and then a bunch of messages like:

U csswg/.htaccess
U csswg/default.css
U csswg/logo-ED.png
cvs.bin checkout: Updating csswg/css-style-attr
U csswg/css-style-attr/Overview.html
U csswg/css-style-attr/Overview.src.html
U csswg/css-style-attr/issues-lc-2009.txt

etc.

CONGRATULATIONS!

You now have a checkout of the csswg CVS repository.

If you want to check out the HTML Working Group's (HTMLWG) html5 repository instead, you can use a check out command with html5 as the project rather than csswg.

First make sure that your Terminal application/window is in the directory where you want to create the “html5” check out, and then execute a command like:

cvs -d :ext:Tantekelik@dev.w3.org:/sources/public co html5

and again, with YOUR username instead of “Tantekelik”.

Aside - Enabling BBEdit CVS Support

If you use the BBEdit text editor:

BBEdit 9.x

You'll see a new CVS menu between the #! and the script icon menu for performing operations on files that are part of a CVS checkout.

Repeat these steps for any other CVS repositories you checkout, substituting their name/folder for “csswg” in the instructions (e.g. “htmlwg”).

BBEdit 7.x

If you're running BBEdit 7.1.x you'll see a new “yellow diamond merge” menu icon between the #! and the script icon menu for performing operations on files that are part of a CVS checkout.

Feel free to add more specific info about other versions of BBEdit.

Aside - Other Editor CVS Support

Other windowing/GUI text editors may have their own ways of enabling CVS support. Feel free to add documentation for those here in their own sections, named similarly to the previous section on Enabling BBEdit CVS Support.

Step 3 - Creating A New Directory

Say you're working on a new spec, CSS3 Foo and want to create the respective directory, “css3-foo”, here's how you do it.

Create the new folder for “css3-foo” in your filesystem.

E.g. on a Mac, go to the “csswg” folder in the Finder, and choose “New Folder” (cmd-shift-N) and rename the folder to “css3-foo” (without the quotes).

Or cd to that directory and do a

mkdir css3-foo

command in your terminal/shell.

Then you need to do an explicit cvs add on the directory, e.g.

cvs add css3-foo

You should get a message back like:

Directory /sources/public/csswg/css3-foo added to the repository

If you get a message like:

cvs-debian-1.12.13 checkout: cannot find module `csswg/css3-foo - New directory
' - ignored

Ignore it.

Now cd into that directory

cd css3-foo

CVS needs at least one file in a new directory for that new directory to be propagated to the server.

Create your new HTML pre-processor source file and name it something like: Overview.src.html

and save it in the aforementioned css3-foo directory.

To commit this file and thus create the new directory, you have to do a cvs add, e.g. from the shell.

cvs add Overview.src.html

You should see messages like:

cvs.bin add: scheduling file `Overview.src.html' for addition
cvs.bin add: use 'cvs.bin commit' to add this file permanently

Now you have to do a cvs commit of the file and the directory, which means first going to (cding up to) its parent.

cd ..

Do a cvs commit with the name of the directory explicitly (doing so is safer, because otherwise you'll checkin anything you've changed at that directory or inside an descendant folder/directory), with a proper commit message.

copy the following line:

cvs commit -m "YOUR COMMIT MESSAGE HERE" css3-foo

and replace

YOUR COMMIT MESSAGE HERE

with something more meaningful, like:

creating css3-foo for the CSS3 Foo module spec

Now you should see a set of messages like:

cvs commit: Examining css3-foo
RCS file: /sources/public/csswg/css3-foo/Overview.src.html,v
done
Checking in css3-foo/Overview.src.html;
/sources/public/csswg/css3-foo/Overview.src.html,v  <--  Overview.src.html
initial revision: 1.1
done
cvs-debian-1.12.13 checkout: Updating csswg/css3-foo

CONGRATULATIONS!

You've checked in your first new directory and file.

Aside - What is this odd vim editor

IF you forget to type -m and a commit message in the cvs command line, e.g. type something like:

cvs commit css3-foo

THEN

You might quickly see a message like:

cvs commit: Examining css3-foo

And then be teleported into a terminal based text editor.

In MacOS X 10.6 Terminal, the title of the terminal window will change to indicate the name of the text editor (e.g. vim is indicated by something like

Terminal — vim — 80×24

Regardless of which editor, you'll see lines at the top starting with:

CVS: ----------------------------------------------------------------------
CVS: Enter Log.  Lines beginning with `CVS:' are removed automatically

IF you're using VIM:

type 'i' to go into INSERT mode (you should see a bold – INSERT – at the bottom of the terminal screen)

Type in a commit message for the new directory and file and press return.

then press the 'esc' (escape) key

and type the keys ':' 'w' 'q' (one at a time, without the quotes or spaces)

and press the enter/return key.

You should see messages like:

RCS file: /sources/public/csswg/css3-foo/Overview.src.html,v
done
Checking in css3-foo/Overview.src.html;
/sources/public/csswg/css3-foo/Overview.src.html,v  <--  Overview.src.html
initial revision: 1.1
done
cvs-debian-1.12.13 checkout: Updating csswg/css3-foo

Your code has been checked in with the comments you wrote in the vim edited file.

In order to avoid vim popping up like that in the future, be sure to to always explicitly specify a commit message with -m like

cvs commit -m "YOUR COMMIT MESSAGE HERE" css3-foo

(If you do want to use an editor, just not vim, see the -e option in the CVS manual for various ways to do that.)

Aside - Check In A New File From BBEdit

How to check in a new file from BBEdit.

Open the new file e.g. Overview.html in BBEdit

Choose “Add” from the CVS (or mergeicon) menu.

Choose “Commit File…” from the CVS (or mergeicon) menu.

You will be presented with a “Commit File” modal dialog.

Enter your checkin comments for the file and click (OK).

Aside - Check In Multiple New Files From BBEdit

How to check in multiple files from BBEdit.

IF all the new files are in the same folder (or descendants of that folder)

THEN open a file that folder

and choose “Commit Parent Folder…” from the CVS (mergeicon) menu.

You will be presented with a “Commit Message” modal dialog.

Enter your checkin comments for all the files you have changed in that folder or its descendants and click OK.

Step 4 - How To Edit An Editors Draft

Open the Overview.src.html file in the directory of the spec you want to edit.

Make sure you edit the *.src.html version, NOT the *.html version.

Look for the W3C style sheet <link> tag - it will look something like this:

<link rel="stylesheet" type="text/css"  
      href="http://www.w3.org/StyleSheets/TR/W3C-CR">

It may end in “W3C-WD” or “W3C-PR” or something else. Make sure it is the EDITOR's stylesheet by using this <link> element:

<link rel="stylesheet" type="text/css"  
      href="http://www.w3.org/StyleSheets/TR/W3C-ED">

You'll probably need to make other edits. You should check a good editor's draft as an example, e.g. CSS3 Color is pretty good.

One thing to make sure is that the “Previous version:” at the top of the document links to the absolute latest official /TR/ version of the document.

Step 5 - Update Your CVS Checkout

Both before you start editing a document, and when you're ready to check in a document, you should update your local CVS checkout.

cd to your CVS checkout, e.g. if your check out is in your home directory:

cd ~/csswg
cvs up -d

IF it seems to stall and not do anything, or eventually gives an error message like:

lionel-hutz.w3.org: Connection refused
cvs [update aborted]: end of file from server (consult above messages if any)

OR an error message like:

cvs [update aborted]: cannot exec value: No such file or directory
cvs [update aborted]: end of file from server (consult above messages if any)

THEN check to see if your CVS_RSH is defined by trying:

echo $CVS_RSH

IF you get nothing but a blank line or something other than “ssh”, THEN do this (you likely need to setup your CVS_RSH system variable as documented in Step 1 setup cvs_rsh) :

export CVS_RSH=ssh

THEN retry the cvs up line:

cvs up -d

You should see messages like:

cvs.bin update: Updating .
cvs.bin update: Updating css-style-attr

… etc.

If you see a line starting with a “M”, like:

M css3-color/Overview.src.html

That means that you have a locally modified version of that file and should verify your changes and check it in.

If you see a line starting with a “P”, like:

P css3-background/Overview.src.html

That means that that file was updated with a “P”artial download (CVS was able to be more efficient by only downloading diff).

If you see a line starting with a “U”, like:

U css3-transitions/step.png

That means that that file was “U”pdated with a full download.

Step 6 - Post Process CSS Src

Using the web form

Go to:

http://www.w3.org/Style/Group/css3-src/bin/postprocess-file

Click (Choose File) and select the Overview.src.html file on your local machine that you want to post-process (you should do this when you're ready to check it in).

Choose (*) Generated HTML - radio button

Click the (Submit) button

Save the page (e.g. in Firefox, choose the “Save Page as…” menu item from the “File” menu, be sure to choose “Web page, HTML only” from the “Save as” popup), name the file Overview.html (without the quotes), and save it right next your Overview.src.html - you'll likely be replacing an older version, that's ok, go ahead and confirm (command-R in the replace dialog).

Using a command-line script

If you're on a system with curl on it, just save the following line to a file somewhere in your executable path:

curl -u USERNAME:PASSWORD -F file=@Overview.src.html -F group=CSS -F output=html -F method=file http://cgi.w3.org/member-bin/process.cgi -o Overview.html''

(Replace the USERNAME:PASSWORD with your W3C username and password, the same that you would enter when visiting the web form linked above.)

Mark the file as executable, then just run it from within the folder of the spec you're working on. It will automatically submit Overview.src.html to the post-processor and save the results to Overview.html.

Committing

Now when you check in your Overview.src.html file be sure to also check in Overview.html to keep them sync.

You can also just check-in from their parent folder by cding in a terminal window to their directory and then:

cvs -m "COMMIT MESSAGE HERE" commit

where you replace COMMIT MESSAGE HERE with a message that applies to all the files you're checking in.

Verify Your CVS Setup

“cd” to a directory that you have a checkout and try a

cvs version

IF you get an error message like:

Client: Concurrent Versions System (CVS) 1.11.18 (client/server)
 lionel-hutz.w3.org: Operation timed out
Server: cvs [version aborted]: end of file from server (consult above messages if any)

THEN something is wrong with your CVS setup probably.

TRY:

echo $CVS_RSH

IF it shows just a blank line then you need to set it:

export CVS_RSH=ssh

try again:

cvs version

Authenticity Of Host Cant Be Established

IF you see a message like (On MacOSX 10.4 at least) :

The authenticity of host 'dev.w3.org (128.30.52.19)' can't be established.
RSA key fingerprint is fb:30:ab:09:1c:b3:1a:74:93:67:57:fd:69:16:0b:97.
Are you sure you want to continue connecting (yes/no)?

Verify that the fingerprint is correct and then type in

yes

and press return.

you may see a message like:

Warning: Permanently added 'dev.w3.org' (RSA) to the list of known hosts.

You may be asked:

Enter passphrase for key '/Users/USERNAME/.ssh/id_dsa': 

where USERNAME is your username alias on your local system.

Enter your pass phrase for your key.

IF you keep getting asked that for every CVS command you run,

THEN try

ssh-add ~/.ssh/id_dsa

you might get an error like:

Could not open a connection to your authentication agent.

TRY

ssh-agent -s

Now you might see something like:

SSH_AUTH_SOCK=/tmp/ssh-VWXYZVWXYZ/agent.555; export SSH_AUTH_SOCK;
SSH_AGENT_PID=333; export SSH_AGENT_PID;
echo Agent pid 333;

(numbers and ssh-VWXYZVWXYZ string obscured with fakes for the sake of documentation).

Now try:

eval `ssh-agent -s`
ssh-add ~/.ssh/id_dsa

and you might see a message like:

Enter passphrase for /Users/USERNAME/.ssh/id_dsa:

where USERNAME is your username alias on the system.

Enter your pass phrase for your key.

Then you might see a message like this: (at least on Mac OS X)

Identity added: /Users/USERNAME/.ssh/id_dsa (/Users/USERNAME/.ssh/id_dsa)

Now try:

cvs version

And you should get messages like:

Client: Concurrent Versions System (CVS) 1.11.18 (client/server)
Server: Concurrent Versions System (CVS) 1.11.22 (client/server)

Aside - Mac OSX UI To Set Environment Variables

On Mac OS X 10.5 and later, download and double-click install the “Environment Variable Preference Pane 1.3” from:

Choose “System Preferences…” from the Apple menu.

Choose the “Environment Variables” preference pane.

Click the “+” to add a new entry.

double-click the new “key” entry in the list and change it to CVS_RSH.

double-click the new “value” entry in the list and change it to ssh.

Quit System Preferences.

Logout of your machine and log back in.

From now on, the CVS_RSH environment variable is automatically set for all applications whenever you log into your account on your machine. This means it will work both with terminal/shell applications, and nice text editors that have integrated CVS support for example.

W3C Member-Only CVS Repository

If you've gotten this far, and you happen to also be a W3C Member (or a W3C Invited Expert that's been granted Member Access), you might want to also check-out and help with some W3C Member-only parts of w3.org.

Assuming you've already successfully checked-out and checked-in to W3C's Public CVS repository by following the above steps, here's what you need to use the W3C Member-Only CVS Repository.

First, make sure your staff contact (in whatever W3C working group you're working with/in) has upgraded your CVS account access for member-only areas, in particular, for cvs.w3.org.

Just as you checked out into a new directory from the public repository, you'll do the same here, just with a different command line.

In a Terminal window, be sure to cd to the directory you want to create the new checkout, then modify this command line:

cvs -d Tantekelik@cvs.w3.org:/w3ccvs co WWW

with YOUR username instead of “Tantekelik” (used only as a placeholder in these examples)

Note that your W3C username is CASE-SENSITIVE, be sure to enter it precisely.

Now execute the command line.

You might see a message like:

The authenticity of host 'cvs.w3.org (128.30.52.19)' can't be established.
RSA key fingerprint is fb:30:ab:09:1c:b3:1a:74:93:67:57:fd:69:16:0b:97.

That's the right one. If you get a different fingerprint back you're being hacked.

Then when asked:

Are you sure you want to continue connecting (yes/no)?

Answer:

yes

Then you'll likely get a warning like:

Warning: Permanently added 'cvs.w3.org' (RSA) to the list of known hosts.

IF you get messages like:

cvs.bin checkout: Updating WWW
cvs.bin checkout: cannot open directory /w3ccvs/WWW: Permission denied
cvs.bin checkout: skipping directory WWW

Then you don't have access to the top level WWW directory. You'll have to pick a subdirectory instead, perhaps associated with the working group you're working with, e.g. for the W3C CSS Working Group, use a command like this instead:

cvs -d Tantekelik@cvs.w3.org:/w3ccvs co WWW/Style/Group

again with your username instead of “Tantekelik”.

You SHOULD see a message like:

cvs.bin checkout: Updating WWW/Style/Group

and then a bunch of messages like:

U WWW/Style/Group/970117-usersettings.html
U WWW/Style/Group/CSS-X-schema.gif
U WWW/Style/Group/CSS-X-schema.idraw
U WWW/Style/Group/CSS-X-small.gif
U WWW/Style/Group/CSS-X.html
U WWW/Style/Group/CSS-selectors.html
U WWW/Style/Group/History.html

etc.

This might take some time to check out all of WWW/Style/Group, so just let it run for a while.

The total checkout size might be in the range of about 220MB or a bit more (depending on how much has been added since these instructions were updated).

If it seems to get “stuck”, i.e. you've left it running for a while, and it's stopped on a status line like:

cvs.bin checkout: Updating WWW/Style/Group/2002

You can try ctrl-c to stop the check out - whereby it will probably give you messages like:

^Ccvs [checkout aborted]: received interrupt signal
cvs [checkout aborted]: received interrupt signal

Now go the specific directory you checked out:

cd WWW/Style/Group

and restart your checkout:

cvs up -d

If it still seems to stall in the same place, e.g. on

cvs.bin checkout: Updating WWW/Style/Group/2002

Just give it a bit longer - there's a 100+ MB .rm file in that directory that may just be taking a while to pull down.

Eventually, you should see a bunch of cvs.bin updated: Updating … lines like:

cvs.bin update: Updating .
cvs.bin update: Updating 2003
cvs.bin update: Updating 2003/WD-css3-content-20030514
cvs.bin update: Updating 2003/WD-css3-template-20030514
cvs.bin update: Updating 2004

etc. Just give a little while to finish with something like:

cvs.bin update: Updating pjirc/img
cvs.bin update: Updating pjirc/snd
cvs.bin update: Updating test-suite

CONGRATULATIONS!

You now have a checkout of the W3C Member-Only WWW/Style/Group CVS repository.

If you're in the CSS Working group, you probably also want to check out the WWW/Style/CSS CVS repository. Do a quick:

pwd

if the path returned ends with “/WWW/Style/Group” then cd back out of it:

cd ../../..

and then issue a new check out command like before but with the WWW/Style/CSS:

cvs -d Tantekelik@cvs.w3.org:/w3ccvs co WWW/Style/CSS

again with your username instead of “Tantekelik”.

You should see messages like:

cvs.bin checkout: Updating WWW/Style/CSS
U WWW/Style/CSS/.Disclosures.var
U WWW/Style/CSS/.Overview.var
U WWW/Style/CSS/.htaccess

… etc.

In fact, if all you wanted was stuff inside WWW/Style/CSS, then you can simply check that out instead of checking out WWW/Style/Group. As of this writing the WWW/Style/CSS checkout may take about 1.31GB (yes gigabytes, that's not a typo) for over 250,000 files.

Creating new directories, getting updates, and checking in works exactly the same on cvs.w3.org as for the public repository. All the repository-specific information is contained in the folders of your checkout, so CVS doesn't have to be told which server to get updates from etc.

See Also

1)
Close
2)
OK