cvs.txt

====== W3C CVS For Dummies ======

2010-234 Tantek Çelik - originally drafted (with incremental updates since)

===== 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:
  - your W3C username - you need this for communicating with the W3C's CVS server
  - your public key - you need to setup SSH keys for yourself.
    * this might be helpful: [[https://developer.mozilla.org/en/Using_SSH_to_connect_to_CVS#Generating_an_SSH_key|Mozilla Developer Network: Generating an SSH key]]


===== Step 0 - Install CVS =====
You need to first install CVS on your system.

If you have a Mac:
  * install XCode.  It helps if you're using a fairly new OS X version (e.g. 10.6 Snow Leopard) and XCode.
  * install MacPorts (citation/download link needed)
  * ''sudo port install cvs''

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)

<code bash>export CVS_RSH=ssh</code>

You'll want to setup that up to happen automatically for you, and there are some instructions later for doing so.

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

<code bash>echo $CVS_RSH</code>

You should see a message like:

<code>ssh</code>

followed immediately by a prompt.

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) 
  * https://developer.mozilla.org/en/Using_SSH_to_connect_to_CVS#Setting_up_CVS_to_use_SSH


===== Step 2 - How To Do Secure Checkouts  =====
How to do secure checkouts that all you to check in.

  * go http://dev.w3.org/cvsweb/
  * copy the line that starts with:
    * ''CVSROOT=:pserver:anonymous@dev.w3.org:/sources/public''
    * copy the part after "CVSROOT="
  * change ''pserver'' to ''ext''
  * change ''anonymous'' to your W3C username

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.

  * prefix it with "cvs -d" like this:
    * ''cvs -d :ext:Tantekelik@dev.w3.org:/sources/public''
  * put "co csswg" at the end like this:
    * ''cvs -d :ext:Tantekelik@dev.w3.org:/sources/public co csswg''
  * now use "cd" in your terminal/shell window/application to navigate to the directory where you want to create a new "csswg" directory.
  * execute this command in your shell (it will create a new directory called csswg)

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

You might see a message like:

<code>
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.
</code>

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

Then when asked:

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

Answer:

<code bash>yes</code>

Then you'll likely get a warning like:

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



IF you get an error message like

<code>Permission denied (publickey).</code>

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)  ((OK))   |
+-----------------------------------------------+
</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:

<code>Identity added: /Users/USERNAME/.ssh/id_dsa (/Users/USERNAME/.ssh/id_dsa)</code>

where USERNAME is your login alias for your client box.


IF you get an error message like:

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

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

  * you might have taken too long to enter your pass phrase in the previous step
    * try the previous step again, and promptly enter your pass phrase


You SHOULD see a message like:

<code>cvs.bin checkout: Updating csswg</code>

and then a bunch of messages like:

<code>
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
</code>
...

etc.


CONGRATULATIONS!  

You now have a checkout of the ''csswg'' CVS repository.
 

==== Aside - Enabling BBEdit CVS Support ====

If you use the BBEdit text editor:

  * Go to the ''BBEdit'' menu
  * Choose ''Preferences...''
  * Click on ''Tools'' in the left column list of preference panes
  * Check ''|x| CVS Integration''
  * Click the ''(Save)'' button and close the ''BBEdit Preferences'' window.
  * Quit BBEdit and relaunch.

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 

<code bash>mkdir css3-foo</code> 

command in your terminal/shell.

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

<code bash>cvs add css3-foo</code>

You should get a message back like:

<code bash>
Directory /sources/public/csswg/css3-foo added to the repository
</code>

If you get a message like:

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

Ignore it.

Now cd into that directory

<code bash>cd css3-foo</code>

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.

<code bash>
cvs add Overview.src.html
</code>

You should see messages like:

<code bash>
cvs.bin add: scheduling file `Overview.src.html' for addition
cvs.bin add: use 'cvs.bin commit' to add this file permanently
</code>

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

<code bash>
cd ..
</code>

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:

<code bash>
cvs commit -m "YOUR COMMIT MESSAGE HERE" css3-foo
</code>

and replace <code bash>YOUR COMMIT MESSAGE HERE</code> with something more meaningful, like:
<code bash>creating css3-foo for the CSS3 Foo module spec</code>

Now you should see a set of messages like:

<code bash>
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
</code>

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:

<code bash>cvs commit css3-foo</code>

THEN

You might quickly see a message like:

<code bash>
cvs commit: Examining css3-foo
</code>

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 — 80x24''

Regardless of which editor, you'll see lines at the top starting with:
<code bash>
CVS: ----------------------------------------------------------------------
CVS: Enter Log.  Lines beginning with `CVS:' are removed automatically
</code>

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:

<code bash>
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
</code>

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

<code bash>
cvs commit -m "YOUR COMMIT MESSAGE HERE" css3-foo
</code>


==== 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 (mergeicon) menu item.

Choose "Commit File..." from the (mergeicon) menu item.

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 (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:

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

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:

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

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:

<code bash>
cd ~/csswg
cvs up
</code>

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

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

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

<code bash>
echo $CVS_RSH
</code>

IF you get nothing but a blank line then first do:

<code bash>
export CVS_RSH=ssh
</code>

THEN retry the cvs up line:

<code bash>
cvs up
</code>

You should see messages like:

<code bash>
cvs.bin update: Updating .
cvs.bin update: Updating css-style-attr
</code>
...
etc.

If you see a line starting with a "M", like:

<code bash>
M css3-color/Overview.src.html
</code>

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:

<code bash>
P css3-background/Overview.src.html
</code>

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:

<code bash>
U css3-transitions/step.png
</code>

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


===== Step 6 - Post Process CSS Src =====

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).

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:

<code bash>
cvs -m "COMMIT MESSAGE HERE" commit
</code>

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

<code bash>
cvs version
</code>

IF you get an error message like:

<code bash>
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)
</code>

THEN something is wrong with your CVS setup probably.

TRY:

<code bash>
echo $CVS_RSH
</code>

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

<code bash>
export CVS_RSH=ssh
</code>

try again:

<code bash>
cvs version
</code>



==== Authenticity Of Host Cant Be Established ====
IF you see a message like (On MacOSX 10.4 at least) :

<code bash>
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)?
</code>

Verify that the fingerprint is correct and then type in

<code bash>
yes
</code>

and press return.

you may see a message like:

<code bash>
Warning: Permanently added 'dev.w3.org' (RSA) to the list of known hosts.
</code>

You may be asked:
<code bash>
Enter passphrase for key '/Users/USERNAME/.ssh/id_dsa': 
</code>

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

<code bash>
ssh-add ~/.ssh/id_dsa
</code>

you might get an error like:

<code bash>
Could not open a connection to your authentication agent.
</code>

TRY

<code bash>
ssh-agent -s
</code>

Now you might see something like:

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

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

Now try:

<code bash>
eval `ssh-agent -s`
ssh-add ~/.ssh/id_dsa
</code>

and you might see a message like:

<code bash>
Enter passphrase for /Users/USERNAME/.ssh/id_dsa:
</code>
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)

<code bash>
Identity added: /Users/USERNAME/.ssh/id_dsa (/Users/USERNAME/.ssh/id_dsa)
</code>

Now try:
<code bash>
cvs version
</code>

And you should get messages like:
<code bash>
Client: Concurrent Versions System (CVS) 1.11.18 (client/server)
Server: Concurrent Versions System (CVS) 1.11.22 (client/server)
</code>

==== 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:
  * http://www.apple.com/downloads/macosx/system_disk_utilities/environmentvariablepreferencepane.html

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.

====== See Also ======
  * [[test/cvs|Guide to CVS]] - some good command overviews, except IGNORE the bits about "$CVSROOT" and "Logging in".
  * [[http://annevankesteren.nl/2010/08/w3c-cvs|Anne van Kesteren: Setting up CVS for W3C]]