CVS Instructions

INTRO

We will be using a tag to keep track of which code in CVS is suitable for QA. When code with this tag is checked out of CVS, a "sticky tag" is created on each file (use the cvs status command to see it). Before checking in code changes, this sticky tag must be cleared using the cvs update command. The steps below describe how to this using the CVS command line interface and the WinCVS tool.

WHY DO ALL OF THIS?

This process of creating tags is needed because we use CVS for two different purposes. The first purpose is for pure source code control. We need a way for developers to easily revert to a prior version of their code while they are still in the process of developing new features or fixing bugs. The second purpose is for "release control". We need a way of marking code as being ready for QA and eventually customers.

These two purposes conflict with one another if QA is constantly pulling the latest code from the CVS repository since a developer may have done a check-in for the purpose of getting their code backed-up, sharing code with other developers, or because they have reached a logical level of completion and want to check point their code. By tagging code as being ready for QA, we enable developers to use CVS for source code control as often as they want without fear of interfering with QA or having to hold onto code for long periods of time without any checkpoint or backing up of it.

COMMAND LINE STEPS FOR DEVELOPERS

Check out the code for a project with the "stable" tag name. If necessary, you can check out the latest version of the code, but you should try to limit this to just the files that you are sure you need. To check out the "stable" tag, use the following command:
```
                cvs co -r stable [filename]
   
```
Modifying existing code:
Modify the code and check in your changes as often as necessary. You will need to clear the sticky tag from the files you change before checking in your changes. To do this fun the command:
```
                cvs update -A [filename]
   
```
You only have to remove the sticky tag once from a file. After that you do not need to repeat this step before each commit of changes to a file (until you tag again with the "stable" tag name). You can use "cvs status" or "cvs log" to see if the sticky tag is still present. I believe CVS will prevent you from checking in a file that has the sticky tag set (since this is not a branch tag) so the above step must be done and no harm should come if you do not do it.
Then commit your changes as usual:
```
                cvs commit [filename]
   
```
This will create a new revision while the "stable" tag will still point to the original revision.
Adding new files:
If you want to add new files into CVS after you have checked out the stable tag, you must temporarily remove the stable tag from the directory that the files are in. This is done with the following command:
```
                cd [your_dir]
                cvs update -A
   
```
Then add and commit your file(s) as follows:
```
                cvs add [filename]
                cvs commit [filename]
   
```
Then tag the new code that you checked in with the stable tag:
```
                cvs tag stable [filename]
   
```
Once all of your files have been tagged with the stable tag, you can optionally pull all of the tagged code for this directory again by using the update command:
```
                cd [your_dir]
                cvs update -r stable
   
```
Note that if you are going to be doing additional modifications to the files in this directory you may not want to pull the tag since you will have to clear the tag anyway before making changes to any of the files.
Unit test your code.
Repeat steps 2 and 3 as much as necessary.
Update the CVS "stable" tag to point to your latest version of the files.
```
                cvs tag -F stable [filename]
   
```
You can also set the tag to a specific revision number (for instance, to move the "stable" tag back a version) with the command:
```
                cvs tag -r 1.6 -F stable [filename]
   
```
where 1.6 is the revision number.

WinCVS STEPS

One initial set up step is required becuase WinCVS has customizable menus. Right click on a file in your checked out code and choose the "customize this menu" option. In the "Customize menus" dialog, scroll down the left hand side and ADD the "Create a tag on selection..." option to the left hand side of the dialog. Click OK. Now you will have the ability to update tags on files by right clicking on them.

Check out the code with the "stable" tag name. When you are in the "Checkout settings" dialog, choose the "CHeckout options" tab and check the "By revision/tag/branch" checkbox. Enter "stable" for the name of the tag. Click OK.
This will checkout all of the code marked with the "stable" tag name.
Modify the code and check in your changes as often as necessary. This involves two steps. The first step only needs to be done once (before the first time you check in changes to your file).
Right click on the files to you are modifying and go to the "Update settings" dialog box. Check the "Reset any sticky date/tag/-k options" checkbox. Click OK. You can run the status command to see if the tag was removed from these files.
Commit your changes in the same manner that you do today.
Once you have tested your changes, update the "stable" tag to point to the latest revision of your code that is suitable for QA and other engineers. Right click on the files to be tagged. Go to the "Create a tag on selection..." option. In the "Create tag settings" dialog box enter the New tag name "stable" and check the "Overwrite existing tags with the same name" checkbox. Click OK. You can use the cvs status command to see that the tag has been updated and points to the correct revision number of the file.

STEPS FOR NIGHTLY QA BUILD/DROP:

Note: The "cvs rtag" command used below is an atomic command that operates on the CVS repository regardless of the working copy of the code that you have checked out.

Create a new tag called "qa" that is equal to the current "stable" tag used by development. (May have to delete existing qa tag)
```
                cvs rtag -r stable qa [module]
   
```

Pull the code for a project with the "qa" tag name.


                cvs co -r qa [module]

Build/compile the project.
Test the code.

Eventually mark the qa code as a release candidate ("rc"):


                cvs rtag -r qa rc [module]

USEFUL COMMANDS:

To see tag names and revision number, use the following command:


                cvs log [filename]

                cvs status [filename]

                cvs update -A [filename]

TAG NAMES:

All projects should use the same tag names.

stable	Updated by developers to indicate that the code has been unit tested and is ready for QA.
qa	Indicates that the code is being tested by QA.
rc	Indicates that QA has approved this code as a "Release Candidate".

DEVELOPER GUIDELINES:

Only check in code that compiles.
Only pull code with the "stable" tag. If you need the latest code from another developer, first pull all of the stable code, then only pull those files or packages that you need from the latest cvs branch. Fyi, you may have to use the "cvs -update -A [filename]" command to pull the latest code. The "-A" option is needed to clear the sticky tag from your working copy of the code.
Check in code as often necessary to insure that it is being backed up and to allow you to revert to prior versions if necessary.
Check in code if you need to share it with another developer rather than emailing it or making copies for it in different places.

HOW TO DETERMINE IF FILES HAVE BEEN TAGGED:

If you need to determine whether or not you have tagged files in CVS with the stable tag you can run the command:


cd .../projects/platform


cvs -n update -r stable

The "-n" tells cvs to show you the output of the command without actually executing it.

You'll get a listing of all of the files that cvs was going to update in your working copy of the code.

Some example output is:

M test/src/com/foo/utils/db/publictest/data1/Projects01.csv
cvs server: New directory `test/testData' -- ignored
cvs server: New directory `webmod/ui/META-INF' -- ignored
U src/com/foo/utils/db/package.html

The "M" means that the file has been modified on your local disk and that the code has not been checked in yet (and thus the tag hasn't been updated yet).

The "U" means that the code has been checked in, but that it hasn't been tagged as "stable".

The other lines are new directories that were never added to CVS.