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