Setting W3C CVS Public or Restricted Repositories for Eclipse 3.x

Before starting

1. You MUST have a Java runtime environment (JRE) to run Eclipse. Eclipse 3.x was designed to work with Java runtime environment level 1.4 but seems to work fine with 1.5 as well.
2. You MUST use Eclipse 3.0M6 or later to have the proper support for CVS-SSH2. We strongly suggest the Eclipse Web Tools Platform (WTP) Project version of Eclipse in order to get some useful extensions that are not installed by default with Eclipse. It contains an XML Editor, part of the Web Standard Tools feature, that it is not included in the default distribution.
3. You MUST have a SSH2 public key and a SSH2 private key. You can generate public and private keys using the menu Window, Preferences, select Team/CVS/SSH2 Connection Method in the left tree list, then select the Key Management tab. DSA or RSA are both acceptable. Choose a passphrase for your private key and don't forget to save it. Send the public SSH2 to the Team Contact of your Working Group.
4. Your ssh2 private key MUST be in the openssh format; some of the tools can export keys into the openssh format. If your private key file is named id_rsa or id_dsa, it is already in the right format. For putty-generated keys (.ppk), use the menu Conversions in puttygen.exe to convert your private key.
5. Your SSH2 public key MUST be installed on the proper W3C CVS Repository server and be authorized to access the proper directory. Check with the Team Contact of your Working Group if it is not the case.
6. Depending on the location of your documents, you will have to setup your Eclipse for the W3C Public remote CVS Repository (dev.w3.org) OR the W3C Web site main repository (cvs.w3.org). In either case, you should know which directory to check out from the CVS Repository. If you're not sure which CVS Repository to choose or which directory to check out, please check with the Team Contact of your Working Group.
7. Finally, you MUST know your SSH passphrase, ie the phrase you entered to protect your SSH2 private key. The Team Contact of your Working Group cannot help you here :-).

If you fulfill all of the above requirements, you can start setting up ssh for your Eclipse below.

Setting up ssh

1. Open the preferences dialog accessible from the menu Window, Preferences. Select Team/CVS/Ext Connection Method in the left tree list. On the right side, select Use another connection method type to connect. In the connection type dropdown list, select extssh.
   
2. Now, select Team/CVS/SSH2 Connection Method in the left tree list. On the right side, select the General tab. Make sure you point to the appropriate directory SSH2 home for the location of your ssh2 private key, and use the proper lookup Private keys for the file name of the ssh2 private key (by default, it looks for a file named id_dsa or id_rsa).
   

Setting up the CVS Repository Exploring perspective

1. Select the CVS Repository Exploring perspective using the menu Window, Open Perspective, CVS Repository Exploring (You may need to follow Other... in order to find it). A tab CVS Repositories appears on the top left side of the main working area window.
2. Using the icon in the CVS Repositories tab, add a CVS repository. You now have to setup your Eclipse for the W3C Public remote CVS Repository (dev.w3.org) OR the W3C Web site main repository (cvs.w3.org):

   2.1 For the W3C Public remote CVS Repository (dev.w3.org), fill the options for the CVS Repository as follow:

   Location Host	dev.w3.org
   Location Repository path	/sources/public
   Authentication User	<Your Web login>
   Connection type	extssh

   Note: the password doesn't matter since the CVS server doesn't ask for it.

   

   2.2 For the W3C Web site main repository (cvs.w3.org), fill the options for the CVS Repository as follow:

   Location Host	cvs.w3.org
   Location Repository path	/w3ccvs
   Authentication User	<Your Web login>
   Connection type	extssh

   Note: the password doesn't matter since the CVS server doesn't ask for it.

   
3. Hit the Finish button, Eclipse will validate the connection on finish. It will log on the server, will ask you to include the new server key in his knowledge database, then ask you for your SSH passphrase (ie the phrase you entered to protect your SSH2 private key).

Checking documents out of a CVS Repository

To check out a given module in the CVS repository, follow the instructions given in Eclipse's documentation.

NB: due to access control restrictions, only the first method (checking out a module through the Checkout Wizard) will work for non-W3C Staff on cvs.w3.org.

Editing documents

1. You can edit documents with the Resources perspective. You can select this perspective using the menu Window, Open Perspective. You will get a Navigator tab on the left side of the main window.
2. Open the file you want to edit. You can use alternate editor/view to see the file by using right click, Open With. Depending on your extensions, you can have Ant, XML, XSL, and XSD editors. (Tip: When using the XML Editor, use the key Control+space to open or close tags)

Common CVS operations

CVS operations are accessible using right click on a file or a directory. Synchronize, Commit, or Update are accessible from the Team submenu. To erase your local copy and replace it with the CVS one, use the Replace With submenu, Latest from HEAD.

Note that Eclipse doesn't automatically update the status of the files in the Navigator view. So if a file has been modified using an external process (such as Ant — see also the section Using Ant), you need to refresh the view by right clicking on a file or a directory. Eclipse will refuse to commit a file unless it knows that the file was changed!

Resolving CVS conflicts with Text Compare

CVS conflicts occur when you try to commit a document without checking out its latest version first. Either you forgot to update your version before editing it, or someone changed the CVS repository copy while you were editing.

Use the Synchronize view to resolve conflicts. From there, use Open With Compare Editor option by right clicking on a file. In the Text Compare view, one can navigate through the changes. You get the CVS repository copy (remote copy) of the file on the right side, and the local copy on the left:

In the example above, the Synchronize view shows a need to commit the file CompareEditor1.png and a conflict for the file eclipse.html. We've been editing the version 1.18 of eclipse.html locally while the CVS repository contains the version 1.20. In the Text Compare view of eclipse.html, you can see 3 types of changes as follows (from top to bottom):

1. Both sides made some changes in the paragraph;
2. A change was made in the remote copy;
3. A change was made in your local copy.

Using the Text Compare toolbar, You can copy all non-conflicting changes from right to left (second case above, we decide to keep the remote change) or copy current change from right to left (first case above, we decide to discard the change in the local copy and replace it with the remote change). The third case (we decide to commit the local change) will be resolved once you mark the file as merged. Once you're done, save the local copy again (note that the comparison between the two files is recalculated after saving the local copy), double check the resulting local copy as necessary, and Mark as Merged the file using the Synchronize view. Try to commit the file again. You may need to do more than just copying a current change from left to right sometimes. You can edit the local copy in the Text Compare and copy and paste manually from right to left.

Using Ant

If your project is using Ant, i.e. it contains a build.xml file, Eclipse can run the Ant tasks for you. Open build.xml in the Ant Editor (right click, Open With) and look at the Outline view: it contains the list of tasks. Right click on a task, use Run With submenu, and Ant Build; it will run the default task. In the same Run With submenu, you can use Ant Build... to open a dialog with advanced options. For example, to automatically refresh the navigator after running a task, use the Refresh tab in the advanced options, activate the Refresh resources upon completion option, and indicate the type of refresh to apply. It is highly recommended to use the automatic refresh advanced option when using CVS.

Tip: Once you ran an Ant task, it becomes directly accessible through the menu Run, External Tools.

Eclipse extensions

You MAY consider installing oXygen XML (version 6, license) or XMLSpy as eclipse plug-ins. Those two extensions provide better support for XML, XSD, and XSL documents.

You MAY also install extensions using the menu Help, Software Updates, Find and Install.

For further information about Eclipse, look at the Eclipse documentation.

Troubleshooting

One individual reported the inability of Eclipse to realize that documents have been modified, thus preventing any commit (check in) operations. As of today, no fix has been found unfortunately, even after a complete reinstallation of Eclipse. The only workaround is to rely on an external CVS tool to do the commit operations.