[hyades-dev] Hyades in CVS

[Marcelo Paternostro <marcelop@xxxxxxxxxx>]

The Hyades development is now on CVS.
 If you are a Hyades developers and have write access to the Hyades
CVS repository, this note is supposed to introduce you to the process we
will use and to give you some CVS tips.



CMVC x CVS
===========
*CMVC is the repository we've been using
until now to develop Hyades.



CVS doesn't know about defects.  Actually
the bug tracking system is a different application (named bugzilla) located
at
http://bugs.eclipse.org/bugs

Although CVS doesn't enforce this, you
still need to create a bugzilla defect to describe what you will do.
 The link between the changes and the defect is one of the items of
the process we are creating in order to keep things under control  This
process is described in the table below.

CMVC elements that are not in CVS	Problem	How we are fixing at this time*
"Check in" associated with defect numbers	No simple way to identify why something has changed	We need to indicate the bugzilla defect number that has originated the changes. Using Eclipse, the recommended process to do this is: - On top of a meaningful description, add the defect number in the "Commit Dialog" text box - **After committing the changes, version the changed files.  This can be done by right clicking the files->Team->Tag as version.  The version should be bugzilla_defectNumber
Fix record	No simple way to share a code that is not ready to be build and used by everyone (inside and outside the team)	Make sure you are checking in a good code.  Important:  since there is no lock mechanism (see last line of this table), unless you really like to do merges, it is not recommended to keep editing a file for a long time without checking it in. Usually in a CVS environment you do incremental check ins even when fixing one defect.
Track approval	No simple way for the project leaders to control what is going into the repository	Your project leader must know what you are doing and the code you've changed.
Lock mechanism	No simple way to avoid a file to be edited while you are working on it	Do incremental check ins! Be ready to do merges! Never commit a file without verifying if it was changed by someone else in the last 5 seconds!

* As I've said we all learning here.
 Feel free to suggest changes to the process.

** I've opened a feature request on
Eclipse asking for an improvement on the "Commit Dialog" that
would make easier to tag a group of files after a commit.  If you
think this a good idea,  please add yourself as an observer (this
usually increases the feature priority).  The link is https://bugs.eclipse.org/bugs/show_bug.cgi?id=44923.



Defining a CVS connection in Eclipse
================================



1. Open the CVS perspective
2. Right click the CVS Repository view
and create a new connection
3. Enter the data of the connection
        Host:
dev.eclipse.org
        Repository
Path: /home/tools

        User:
your user id
        Password:
your password

        Connection
type: extssh
        Enable
the "Validate connection on Finish" checkbox


If everything has worked fine, you should
have a connection in the Eclipse's CVS Repository view. You should be able
to expand the Head branch and import any module under it (by right clicking
the modules and selecting "Check out as a project").



Checking In tips
=============



These are the steps to check in a project,
folder(s) or file(s) that exist in your Eclipse workspace:

1. Make sure you have everything in
place.  In other words, that all the files and directories are in
the correct place and that they have the appropriate name.

(*** Important)2. Look at your
files extensions and identify the text and binary files.  Now verify
if Eclipse is properly set (Window->Preference->Team->File Content).

3. Right click the project/folder/file
and select "Team->Synchronize with repository"

4. Before committing the changes (what
can be done in the Synchronization view by right clicking the project or
folder or file), check if you are adding resources that should not be going
to CVS (such as the *.class files and output directories - usually bin).
 If this is the case, you may want to go to "Windows->Preferences->Team->Ignored
Resources" and add to the list all the resources that should never
be sent to CVS.

5. Commit the appropriate files

6. Update your Eclipse workspace with
the changes done by other developers

7. If you want to double check that
everything is ok you can repeat the step 3.  You should get a message
box saying that the Workspace and the Repository have the same files.  If
you want to check the files in the CVS Repository (under the connection
you've created), you will have to refresh the view.



Tips and FAQ
============



a.  There is an incoming and outgoing
portion to the synchronization view.  Also, the synchronization tool
is not smart enough to show the differences between files that have been
changed outside of eclipse.  if you unzip a new source tree on top
of the CVS extract it will assume all files have changed regardless of
whether the content has changed.

b.  When sharing code between developers
(ie. sending code to be reviewed)  working with patches is probably
the best thing as this will minimize the merging effort required.


1.  I want to change my CVS
password.  How do I do this?
SSH into dev.eclipse.org using your
existing username and password.  With the 'passwd' command you can
change your password to whatever you please.  If you do not have a
SSH client because you are using Windows there is a free connection client
called 'putty' which can be downloaded from the internet.  Putty supports
SSH, telnet, and several other protocols.  Another option is to install
cygwin (make sure you add the SSH package during the installation).

2. I want to blow away what is in
the project in my workspace and extract the latest code from the HEAD branch
before working on a new defect.  How do I do this.
The most painless way to globally replace
a projects contents is to use the 'Replace with' action.  There is
a subaction to replace with the latest from HEAD.

3. How can I deleted a directory
so it won't appear when someone does a full extract.?
Only the owner of a directory can remove
it.  And this needs to be done using the file system.  Let me
know if you need to do this.  A workaround that will prevent you from
extract empty directories is to enable the "Prune empty directories"
on the Eclipse CVS preferences.

4. How do I update the documentation
for my plugin?
All *doc.user and *infopop plugins are
in CVS.  For the *doc.user plugins, the topic and index files are
in the root directory while the actual content is in doc subdirectory.
 So you can update the content or index the same way you would update
any java file.



Links
=====



- CVS for the project
In this link you will find the connection
string to access the CVS repository and also the link to navigate the repository
using your browser.  Look for the Hyades modules.

http://dev.eclipse.org/viewcvs/index.cgi/?cvsroot=Tools_Project

- CVS in Hyades
This guide is customized for Hyades.
*Don't use the anonymous login recommended
here.  You should use your Eclipse repository account.

http://dev.eclipse.org/viewcvs/indextools.cgi/~checkout~/hyades-home/docs/Development%20Guide.htm

- CVS Book
This is a very good book.  Chapter
2 could be consider a must read for the ones that will use CVS outside
Eclipse.

http://cvsbook.red-bean.com/

- The CVS manual
Probably this contains much more information
than a developer would need, but...

http://www.cvshome.org/docs/manual


Best regards,

Marcelo Paternostro
IBM Toronto Lab
Voice: 1-905-413-3942
Fax: 1-905-413-4920
internet: marcelop@xxxxxxxxxx