File vendor.readme
Purpose: 1. To define a set of code to be used to test merging or
tracking of vendor (third-party) software using CVS.
2. To describe a script, branchgen.sh, which invokes CVS
import commands to create the example described herein.
3. To describe the use of a modified version of TkCVS
release 5 (Tk 3.6) which has a Module Level Merge
command for merging in vendor or third-party source
code. This modified version is called tkcvs_gene.
4. To list desired improvements to tkcvs
By: Eugene Lee, Aerospace Corporation, 10/4/95
1. To test out the merging or tracking of vendor (third-party) source
releases using CVS, the following set of pseudo code is presented.
This pseudo code was used so that a listing of all the routines can
be easily shown below.
############################### Vendor Code ############################
# | main | get | sort | getsort #
#______________________________________________________________________#
# Rev 1 | program Main | proc Get | | #
# | Revision 1 | Revision 1 | (undefined) | (undefined) #
# | .. | .. | | #
# | Get | .. | | #
# | .. | end | | #
# | end | | | #
#______________________________________________________________________#
# Rev 2 | program Main | proc Get | proc Sort | #
# | Revision 2 | Revision 2 | Revision 2 | (undefined) #
# | .. | .. | .. | #
# | Get | .. | end | #
# | .. | ..(new code)| | #
# | Sort | end | | #
# | Printout | | | #
# | end | | | #
#______________________________________________________________________#
# Rev 3 | program Main | | | proc GetSort #
# | Revision 3 | (deleted) | (deleted) | Revision 3 #
# | .. | | | .. #
# | GetSort | | | .. #
# | Printout | | | end #
# | end | | | #
############################### Vendor Code ############################
Vendor Code :In Revision 1 only program Main and proc Get are defined.
In Revision 2 proc Sort is added, proc Get is modified, and
program Main is modified.
In Revision 3 proc GetSort is added to replace the functions
previously provided by procs Get and Sort. Procs Get and Sort
are deleted. Program Main is modified.
The changes between revisions 1, 2, and 3 includes new and
deleted routines. The purpose of introducing new and deleted
routines is to point out how the CVS merging capability will
not handle new and deleted routines. New and deleted routines
must be handled manually. In section 3, when TkCVS is used for
merging, specifics on how to do this is presented.
################ Local Code #################
# | main | get #
#___________________________________________#
# Rev 1 | program Main | proc Get #
# | Revision 1 | Revision 1 #
# | .. | .. #
# | ..(local code) | .. #
# | Get | end #
# | .. | #
# | end | #
################ Local Code #################
Local Code: In Revision 1, the local code is identical to the vendor code
except for the ..(local code) before the Get statement.
Revisions 1, 2, and 3 of the vendor code will be imported with cvs import
commands into CVS module Examples/Vendor (that's module Vendor in directory
Example in the repository). Revision 1 of the local code will be imported
with the cvs import command into CVS module Examples/Local.
In tkcvs, from the "CVS Log Browser" window, there is a capability to
do merging on individual files from the "HEAD" branch. For large software
projects, which can have hundreds of routines in a module, this capability
in tkcvs is not practical to use for merging or tracking a new release of
the vendor code.
A local modification to TkCVS release 5 (Tk 3.6) was made by E. A. Lee
to incorporate a merging capablility which will operate on all files in
the current module. The command to do this is called "Module Level Merge".
In Section 3, the modified TkCVS program will be used to checkout a copy
revision 1 of the local code. The "Module Level Merge" command will then be
used to merge in changes between revisions 1 and 2 of the vendor code.
After some manual changes to the local code, which will then be tracked
to revision 2, the local code will be checked in. The "Module Level Merge"
command will again be called to merge in changes between revisions 2 and 3
of the vendor code. After some manual changes to the local code, which will
then be tracked to revision 3, the local code will be checked in.
---------------------------------------------------------------------------
2. Script branchgen.sh will create the CVS Modules for the above example.
This script will create all the files described in the above example and
import them into CVS. The local code will go into module Examples/Local.
The cvs command used is:
cvs import -m"Local code used for testing" Examples/Local LOCAL rev1
The vendor code will go into module Examples/Vendor. The cvs commands used
are:
cvs import -m"Vendor code used for testing Examples/Vendor VENDOR rev1
cvs import -m"Vendor code used for testing Examples/Vendor VENDOR rev2
cvs import -m"Vendor code used for testing Examples/Vendor VENDOR rev3
The current version of tkcvs was not used to import the files in this
example since the author of tkcvs stated that he is considering a wholesale
change in the import function. He states that he might:
o Get rid of the way present method of requiring a version number
for the branch and make it static at 1.1.1. The cvs import
commands that are used in branchgen.sh assumes this.
o Change the default vendor branch tag name to "VENDOR". The cvs
import commands that are used in branchgen.sh for the vendor code
follows this.
o Change the baseline tag name to "baseline-x_y" where x.y is the
real software release number. The cvs import commands in branchgen.sh
uses rev1, rev2, and rev3.
To use this script:
o If you have never used cvs and wish to create a new test cvs
for experimenting, do the following:
o From your home directory
mkdir ~/cvstest; cd ~/cvstest
unsetenv CVSROOT
cvsinit <-- you will be prompted to enter the full
path for your CVSROOT source repository
setenv CVSROOT <whatever you entered in response to cvsinit>
The environment variable CVSROOT defined where the CVS repository
is located.
o From a working directory, i.e., ~/tmp_branches :
o Set environment variable CVSROOT to where your CVS repository is.
o Invoke branchgen.sh.
(On the ASC HP network, this file is in ~gene/tclstuff/TkCVS_gene )
In branchgen.sh, after the example files have been imported into CVS,
the CVS module "modules" will be checked out into your home directory.
The script will then cd to ~/modules where file modules will be appended
with the following lines:
#D Examples Directory of testing
#M local Local code used for testing Merge
local Examples/Local
#M vendor Vendor code used for testing Merge
vendor Examples/Vendor
These lines are used by tkcvs for storing names of CVS directories
and modules.
The last line of branchgen.sh will check file modules back into the
repository.
--------------------------------------------------------------------------
3. Using the modified version of TkCVS to run the above example.
The modified version of TkCVS which has the "Module Level Merge" command
is called tkcvs_gene. (On the ASC HP network tkcvs_gene is in /usr/local/bin)
a. From a CVS working test directory, i.e., ~/TESTCVS, invoke tkcvs_gene.
First the local code will be checked out.
o Press the "File->Check Out" selection.
o The "Module Browser" window will appear.
o Double click on Examples in the right scroll list.
o The scroll lists will expand to show all the modules in the
Examples directory.
o Click on module "local" and then press the Check Out button.
o You will be prompted to verify this is what you want. Press OK.
o tkcvs opens up a window showing what was checked out. Press OK to
continue.
o The main TkCVS window will now show module "local" in your working
directory.
o Double click on local in the left scroll list to go to the local
directory.
Merge in differences between revisions 1 and 2 into the local code.
o Press the "File->Module Level Merge" selection.
o The "Module Level Merge With Vendor Code" window will appear.
o Press the "Select Module With Vendor Code From Repository" button.
o The "Select A Module For Vendor Code" window will appear.
o Double click on "Examples" in the right scroll list.
o The listboxes will expand to show all the modules in the Examples
directory.
o Click on module "vendor" and press the OK button.
o In the "Module Level Merge With Vendor Code" window the Vendor
Module entry box will be updated with your selection and all the
revisions that are associated with that module will appear in the
two scroll lists.
o From the left scroll list double click on "rev1" so that the
selection will be placed into the "From" entry box. (Note: To
prevent input errors, you cannot manually enter data into the
"From" and "To" entry boxes.)
o From the right scroll list double click on the "rev2" so that the
selection will be placed into the "To" entry box.
o Press the OK button
o You will be prompted to verify this is what you want. Press OK.
o tkcvs_gene will open up two windows showing what was checked out.
o One will be the output from checking out temp files used by
tkcvs_gene for doing the merge. Press the OK button.
o The other is the cvs output from doing a cvs merge. The output
is:
M /users/s2/gene/TESTCVS/local/main
cvs checkout: Updating /users/s2/gene/TESTCVS/local
RCS file: /users/s2/gene/cvstest/Examples/Vendor/get,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.2
Merging differences between 1.1.1.1 and 1.1.1.2 into get
RCS file: /users/s2/gene/cvstest/Examples/Vendor/main,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.2
Merging differences between 1.1.1.1 and 1.1.1.2 into main
As you can see, files main and get were merged. However, no
reference is made to file sort, which is new to revision 2.
A CVS merge only works on files which are common between the
two releases. Press the OK button
o In the main TkCVS window the right scroll list will show
"ok" for both the get and main files. Press the Status button.
This will refresh the status of the files. The "ok" then becomes
"{Locally Modified}".
o To verify that the merge was done properly you can view either
the main or get files.
o To view file main, either
o Double click on "main" in the left scroll list
o Click on "main" in the left scroll list and then click on the
second button from the right at the bottom of the window.
o If you view main, you will see that vendor changes between
revisions 1 and 2 were properly implemented.
o File sort from revision 2 of the vendor code cannot be merged
into the local code since it is new to revision 2. It must be
manually copied into the local source code. If you invoked
branchgen.sh from ~/tmp_branches revision 2 of the vendor file
sort will be in ~/tmp_branches/Examples/Vendor/V2. From another
hpterm or xterm window cd ~/tmp_branches/Examples/Vendor/V2 and
execute the following command:
cp sort ~/TESTCVS/local
o Return to the main "TkCVS" window press the Status button.
File sort will now appear in the left scroll list. In the right
scroll list this file will be marked as "????".
Checkin revision 2 of the local code
o Since file sort is new to revision 2 and is not known to CVS
module local, it must first be added. Click on "sort" in the
left scroll list, press the "Mark Selected" button, and then
press "File->Add File" selection.
o You will be prompted to verify this is what you want. Press OK.
o Back in the main tkcvs window press the Status button. In the
right scroll list for file sort, "????" will change to
"{Locally Added}".
o Press the "Mark All" button.
o Press the "File->Check In" selection
o The "Commit Changes to a Module" window will appear. Input
"1.2" for the Version number. Input "Local code updated to rev 2"
for the comment. Press the OK button.
o You will be prompted to verify this is what you want. Press OK.
o You will get the following output in the CVS Commit Output window:
Checking in get;
/users/s2/gene/cvstest/Examples/Local/get,v <-- get
new revision: 1.2; previous revision: 1.1
done
Checking in main;
/users/s2/gene/cvstest/Examples/Local/main,v <-- main
new revision: 1.2; previous revision: 1.1
done
Checking in sort;
RCS file: /users/s2/gene/cvstest/Examples/Local/sort,v
done
/users/s2/gene/cvs2/Examples/Local/sort,v <-- sort
initial revision: 1.1
done
Note that sort was checked in with CVS number 1.1 while file main
and get are checked in with CVS number 1.2.
o Press the Quit button to exit from tkcvs. You don't really have
to do this to continue with this example. However, it will
simulate more closely the scenario one goes through when merging
or tracking new release of the vendor code.
b. From the same CVS working test directory as above, i.e., ~/TESTCVS,
invoke tkcvs_gene.
Merge in differences between revisions 2 and 3 into the local code.
o Double click on "local" in the left scroll list to go to the
local directory.
o You could view any of the files to verify that they are at
revision 2.
o Press the "File->Module Level Merge" selection.
o The "Module Level Merge With Vendor Code" window will appear.
o Press the "Select Module With Vendor Code From Repository" button.
o The "Select A Module For Vendor Code" window will appear.
o Double click on "Examples" in the right scroll list.
o The listboxes will expand to show all the modules in the Examples
directory.
o Click on module "vendor" and press the OK button.
o In the "Module Level Merge With Vendor Code" window the Vendor
Module entry box will be updated with your selection and all the
revisions that are associated with that module will appear in the
two scroll lists.
o From the left scroll list double click on "rev2" so that the
selection will be placed into the "From" entry box. (Note: To
prevent input errors, you cannot manually enter data into the
"From" and "To" entry boxes.)
o From the right scroll list double click on the "rev3" so that the
selection will be placed into the "To" entry box.
o Press the OK button
o You will be prompted to verify this is what you want. Press OK.
o tkcvs will open up two windows showing what was checked out.
o One will be the output from checking out a temp files used by
tkcvs_gene for doing the merge. Press the OK button.
o The other is the cvs output from doing a cvs merge. The output
is:
M /users/s2/gene/TESTCVS/local/main
cvs checkout: Updating /users/s2/gene/TESTCVS/local
cvs checkout: cannot find revision rev3 in file get
RCS file: /users/s2/gene/cvstest/Examples/Vendor/main,v
retrieving revision 1.1.1.2
retrieving revision 1.1.1.3
Merging differences between 1.1.1.2 and 1.1.1.3 into main
rcsmerge warning: overlaps during merge
cvs checkout: cannot find revision rev3 in file sort
As you can see, CVS could not find files get and sort since
they have been deleted in revision 3 of the vendor code. A
merge was performed on file main using revision 2 and 3.
However, note that the output indicates that there are
overlaps. This must be fixed manually later (more on this
below). No reference is made to file getsort which is new to
revision 3 of the vendor code. A CVS merge only works on files
which are common between two releases. Press the the OK
button.
o In the main TkCVS window the right scroll list will show
"ok" for the get, main, and sort files. Press the Status button.
This will refresh the status of the files. The status of the
file main becomes "{Locally Modified}" and the status of files
get and sort stays at "ok". These two files are not in revision
3 and must be manually removed.
o Click on get in the left scroll list and then press Marked
Selected.
o Click on sort in the left scroll list and then press Marked
Selected.
o Press "File->Remove Files" selection.
o You will be prompted to verify this is what you want. Press OK.
The output will be:
cvs remove: scheduling get for removal
cvs remove: use 'cvs commit' to remove this file permanently
cvs remove: scheduling sort for removal
cvs remove: use 'cvs commit' to remove this file permanently
Press OK to delete this output window.
o To verify that the merge was done properly you can view either
the main or get files.
o To view file main, either
o Double click on "main" in the left scroll list
o Click on "main" in the left scroll list and then click on the
second button from the right at the bottom of the window.
o If you view main, you will see that vendor changes between
revisions 2 and 3 were properly implemented.
o File getsort from revision 3 of the vendor code cannot be merged
into the local code since it is new to revision 3. It must be
manually copied into the local source code. If you invoked
branchgen.sh from ~/tmp_branches revision 3 of the vendor file
getsort will be in ~/tmp_branches/Examples/Vendor/V3. From another
hpterm or xterm window cd ~/tmp_branches/Examples/Vendor/V3 and
execute the following command:
cp getsort ~/TESTCVS/local
o Return to the main "TkCVS" window and press the Status button.
File sort will now appear in the left scroll list. In the right
scroll list this file will be marked as "????".
o View the file main by double clicking on "main" in the left scroll
list. The editor will show:
program Main
Revision 3
..
<<<<<<< main
.. (local code)
Get
..
Sort
=======
GetSort
>>>>>>> 1.1.1.3
Printout
end
What this says is that CVS could not handle the overlaps. The
overlap is deliniated by the lines
<<<<<<< main
=======
>>>>>>> 1.1.1.3
This file should be edited to yield:
program Main
Revision 3
..
.. (local code)
GetSort
Printout
end
Checkin revision 3 of the local code
o Since file getsort is new to revision 2 and is not known to CVS
module local, it must first be added. Click on "getsort" in the
left scroll list, press the "Mark Selected" button, and then
press the "File->Add Files" selection.
o You will be prompted to verify this is what you want. Press OK.
o Back in the main tkcvs window press the Status button. In the
right scroll list for file sort, "????" will change to
"{Locally Added}".
o Press the "Mark All" button.
o Press the "File->Check In" selection
o The "Commit Changes to a Module" window will appear. Input
"1.3" for the Version number. Input "Local code updated to rev 3"
for the comment. Press the OK button.
o You will be prompted to verify this is what you want. Press OK.
o You will get the following output in the CVS Commit Output window:
Checking in getsort;
RCS file: /users/s2/gene/cvstest/Examples/Local/getsort,v
done
/users/s2/gene/cvstest/Examples/Local/getsort,v <-- getsort
initial revision: 1.1
done
Checking in main;
/users/s2/gene/cvstest/Examples/Local/main,v <-- main
new revision: 1.3; previous revision: 1.2
done
Note that getsort was checked in with CVS number 1.1 while main
was checked in with CVS number 1.3.
o This completes the merging or tracking of the vendor code to rev 3.
---------------------------------------------------------------------
4. Desired improvements to tkcvs:
o When checking in changes to the current directory the "Commit
Changes to a Module" window could use some improvements.
o Rather than letting the user specify the version number, this
window could show the users what the current version number is.
It can then either assign a default number for the new checkin
or else verify that the user assigns a version number that is
higher than the current version number.
o When checking out a module from the "Module Browser" the entry
boxes "Tag A" and "Tag B" could be more descriptive. Perhaps
a button could be defined to be used to invoke a scroll list to
show what the available selections can be. Such a user-interface
policy can eliminate input errors.
o For this example the new and deleted files which must be manually
added or deleted during a merge is easy to identify and implement.
However, when there are many files in a source module, an automated
method to identify new and deleted files between different releases
of the vendor code would be useful. A new tkcvs command "Module
Level Differences" will be implemented by E. A. Lee and added to
tkcvs_gene. This command will use the unix dircmp command. The
output from this command will show/provide:
o What files are not common between two vendor releases,
i.e., new and deleted files.
o Differences between common files from two vendor releases.
o Hardcopy of the differences.
