Forum OpenACS Q&A: Re: CVS
So for the benefit of anyone else just starting out to learn to use CVS (and so that I can refer back to it later!!) here are the precise misconceptions that caused me to have problems with this.
Scenario:
You have built a web service on a previous version of openacs (say openacs-4-6). In doing so you have modified various .adp pages, hacked a plethora of .tcl files and you have a load of stuff in the content repository. You have been careful enough to comment ALL of your changes (you think(!)) - but then again - you can't be absolutely sure.
You now need to upgrade to openacs-4-6-3 because otherwise you will stuck running an outdated version of PostgreSQL (with a buggy pg_dump, or an obsolete date format for instance), and therefore unable to share in the delights of future releases of OpenACS.
You didn't bother to learn to use CVS before you modified the code.
Background:
For anyone new to CVS, in addition to reading the basics about the main development 'trunk' of revisions in a repository and the idea of 'branches' of revisions, you need to know the following if you are to avoid days of frustration not understanding why the wretched thing won't do what you've told it to do:
1) CVS will only 'merge' changes in source code files that have been developed in parallel if they exist on different branches.
2) If you have three tarballs, openacs-4-6, openacs-4-6-yourversion and openacs-4-6-3 you will need to use 'cvs import' to import the source files.
3) You will need to merge your changes into the main trunk which means that you must 'cvs import' into a 'yourversion' branch. Contrary to my misunderstanding you do not have to create that branch with an 'rtag' command. The 'cvs import' command will set up the branch for you if you use the '-b branch_number' option. So don't use 'rtag' for this otherwise you will end up with extra tags and extra confusion.
4) When you specify the branch in the 'cvs import' command you must do so as a revision number. This is not done for you. The first 'cvs import' will be revision 1.1.1, you must therefore specify revision 1.1.2 for your branch. What I did wrong was to create a branch using 'cvs rtag' and wonder how to import source files to it because it had a 5 digit revision number and 'cvs import' only supports a three digit revision number. The reason for this is that new 'outside' sources are always stored in first level branches (see page 113 of http://ftp.cvshome.org/release/stable/cvs-1.11.15/cederqvist-1.11.15.pdf). Any revisions are then stored as leaves on these branches with 4 and 5 digit revision numbers.
5) You have to be telepathic to know that the only way to determine a valid branch number for your imported source is to import openacs-4-6 into the your repository (the trunk by default and revision 1.1.1 in an new, empty repository) and then check it out and run a 'cvs status -v file' on any file in the openacs. This way you can look up the most recent three digit branch revision number and add one to it for your import.
Steps:
1) untar openacs-4-6, openacs-4-6-yourversion and openacs-4-6-3 into their respective directories.
2) Import the original common ancestor (required for merging)
'cd openacs-4-6'
'cvs import -ko -m "openacs-4-6" openacs OpenACS openacs-4-6'
'cvs checkout openacs'
'cd openacs'
'cvs commit' - (not certain if required but doesn't hurt.)
'cvs status -v somefile' - (observe the last used branch revision number)
'cd ..'
3) Import openacs-4-6-yourversion into its own development branch
'cd openacs-4-6-yourversion'
'cvs import -ko -b 1.1.2 -m "openacs-4-6-yourversion" openacs YOUASVENDOR openacs-4-6-yourversion'
'cvs checkout -r openacs-4-6-yourversion openacs'
'cvs commit'
'cd ..'
4) Import openacs-4-6-3 into the same 'trunk' of revisions as openacs-4-6 was imported into
'cd openacs-4-6-3'
'cvs import -ko -m "openacs-4-6-3" openacs OpenACS openacs-4-6-3'
'cvs checkout -r openacs-4-6-3 openacs' - (check you get an openacs-4-6-3 checked out. Do a 'cvs status v somefile' in the checked out directory if you like)
'cd ..'
5) Merge the wretched thing
'cvs checkout -j YOUASVENDOR openacs' > somefile 2>&1
Hopefully - Hey Presto!
Some tidying up:
-ko means don't substitute keywords. If you leave this out you will get conflicts in every merged file because of the CVS entries in the OpenACS remarks block at the top of every file.
-j means 'join'. I found some apparently helpful docs on the internet that turned out to be misleading over this. In the situation we have here only one join is needed. The command in step 5 says:
"Checkout openacs from the repository having joined it with the YOUASVENDOR branch."
CVS replies:
"OK, I will compare the most recent committed revision of YOUASVENDOR with the most recent ancestor that it shares with OpenACS (the main trunk) and I will incorporate any differences between them into the main trunk.
I hope this helps someone.
And many thanks Nis for your support.
Regards
Richard
