Dev:Ref/GoogleSummerOfCode/2006/CVS guide

Working with CVS for Summer of Code 2006

We've decided to use one tree with three branches, and make merges optional. This tree is separate from the main blender tree from the bf-blender cvs repo, and the main blender tree is imported into this one as third party sources. The branches of this tree are accessed as follows:

Environment Setup

Make sure that you have set up your environment to use ssh with cvs, i.e.,

export CVS_RSH=ssh

if you use csh or tcsh

setenv CVS_RSH ssh

Optionally, you can use the p.b.o website to upload some ssh public keys so that you don't have to type a password every time you access the repository. If you are new to ssh, and keys, etc, just ask for a more detailed elaboration.

Note that windows users may need to do something a bit different with regards to handling ssh.

Checking Out A Branch

The cvs module name is soc-blender and there are three branches that are named after the student coders.

I'm going to pretend I'm sionix. Here is how I would check out my branch ('\' at the end of a line means the line is long and is continued on the next line)

$ cvs -z3 -d:ext:sionix@cvs.blender.org:/cvsroot/soc-2006 \
   co -r sionix soc-blender

(unless sionix has uploaded his ssh public key, he will need to enter his p.b.o password)

This will create a directory called soc-blender with sionix's branch inside it.

We can confirm that this is the right branch using 'cvs status' on a file:

$ cd soc-blender
$ cvs status README

===================================================================
File: README            Status: Up-to-date

   Working revision:    1.1.1.1
   Repository revision: 1.1.1.1 /cvsroot/soc-2006/soc-blender/README,v
   Sticky Tag:          sionix (branch: 1.1.1.1.2)
   Sticky Date:         (none)
   Sticky Options:      (none)

Henceforth, sionix can do cvs update, commit, etc as usual, and it will only affect his branch, provided that he does not reset the sticky tag. Before committing, it may be prudent to do a cvs status on a file to make sure you are indeed affecting the right branch.

bf-blender Source Tree Imports

This is something that students will not usually do (unless they are keen and want to), but they should be aware when this happens: occasionally (say weekly, but it can even be done on request if something is needed), we can import the latest sources from the bf-blender source tree into the BLENDER_DIST branch of the soc-blender tree. This will be effortless: since none of you are working on the BLENDER_DIST branch there should be no conflicts. Also, this will not affect your branches so you can work as usual, and ignore this import if you wish. You will get no conflicts from this action, and life will be good. There is more information about how this is done near the end of this document.

Merging To Student Branches

Well, how do the changes in the BLENDER_DIST branches get propagated to your development branch? This is through merging BLENDER_DIST onto the branch. I recommend checking out a separate working directory to do merges, so as not to damage any un-committed work (but I would advise you to commit any work before a merge). So, it would go something like this the first time:

# checkout new working directory
$ cvs -z3 -d:ext:sionix@cvs.blender.org:/cvsroot/soc-2006 \
   co -kk -r sionix soc-blender

# merge BLENDER_DIST onto our sionix branch
$ cd soc-blender
$ cvs up -kk -jBLENDER_DIST

# fix conflicts if any then commit:
# cvs commit

What happened above is that any differences to the BLENDER_DIST branch since its creation were merged into the sionix branch. Note the -kk's: they are there so that keyword expansion does not happen and so the merge will be a lot smoother (otherwise there will be many conflicts related to the $Id tags that are usually at the top of files).

Now, this is really really really important! Be sure to note the date when you did your last merge! The next time you merge you will need this information, because you will no longer be merging the changes since the creation of the BLENDER_DIST branch, but will instead be merging the changes between the last time you merged and now.

For the sake of example, suppose the last time you merged your sources was on June 10, 2006. This time when you merge, the procedure will look like this:

# checkout new working directory
$ cvs -z3 -d:ext:sionix@cvs.blender.org:/cvsroot/soc-2006 \
   co -kk -r sionix soc-blender

# merge changes to BLENDER_DIST since last merge
# onto our sionix branch
$ cd soc-blender
$ cvs up -kk -j BLENDER_DIST:2006-06-10 -j BLENDER_DIST

# fix conflicts if any then commit:
# cvs commit

One last thing, when you merge doing the steps above it does not modify the repository in any way, just your local copy, until you do the 'cvs commit'. So if you get freaked out because the conflicts are getting ugly, you can just abort the merge and ask for help or something.

One more last thing: I am not a cvs guru, I just basically read the docs and learn things well enough to get the task done. If you want to find out more, or check whether I'm out to lunch, I would recommend reading the relevant section of the cvs manual:

https://www.cvshome.org/docs/manual/cvs-1.12.12/cvs_5.html#SEC56

One final last thing, for you cvs newbies, I'd recommend setting up a .cvsrc file in your home directory that looks something like this:

cvs -z3 -q
diff -up
update -Pd
checkout -P
rdiff -u

These are nice options for compression, etc.

Do's And Don't's

Just a few do's & don't's (well, mostly don't's):

• Don't commit files that are in msdos text format - check your editor settings! If in doubt, run 'file' on a file to report its status, e.g.:

$ file README
README: ASCII English text

$ unix2dos README
$ file README
README: ASCII English text, with CRLF line terminators

Try to keep the style and indentation of your work similar to what is currently in the blender sources, e.g., use tabs for indentation rather than spaces. There are some docs about conventions that are often followed here:

http://www.blender.org/modules.php?op=modload&name=documentation&file=index

OK, that's it for now, feel free to send any questions to the list.

Notes For Future SoC Maintainers

Here are some notes to give the next SoC maintainer a headstart (in case I get hit by a truck or get disgruntled) for the next time that Blender participates in Summer of Code.

Here is how the SoC CVS repository was imported from bf-blender sources this year (assuming the cvs username 'hos'):

 cvs -z3 -d:ext:hos@cvs.blender.org:/cvsroot/bf-blender \
    export -D now blender
 mv blender blender-export
 cd blender-export
 cvs -z3 -d:ext:hos@cvs.blender.org:/cvsroot/soc-2006 \
    import -m "Initial import of blender CVS as soc-blender" \
    soc-blender BLENDER_DIST BLENDER_CVS_2006_05_28

Some changes to the CVSROOT directory were made. Group write for 'val-tags' was needed. 'loginfo', 'log_accum.pl', 'commmitinfo', 'commit_prep.pl' and 'commitcheck' were copied from the last SoC repository, with any references to the old repository changed (e.g., soc-2005 becomes soc-2006, etc). Also make sure to change the ownership and permissions for these files accordingly. A directory called 'commitlogs' containing a file named 'other' (created by 'touch' is sufficient) is needed.

Here are how the branches were created:

 cvs -z3 -d :ext:hos@cvs.blender.org:/cvsroot/soc-2006 co soc-blender
 cd soc-blender
 cvs tag -b sionix
 cvs tag -b nicholasbishop
 cvs tag -b artificer

Here is how a future import of sources might look, for merging, on say, June 10, 2006:

 cvs -z3 -d:ext:hos@cvs.blender.org:/cvsroot/bf-blender \
    export -D now blender
 mv blender blender-export
 cd blender-export
 cvs -z3 -d:ext:hos@cvs.blender.org:/cvsroot/soc-2006 \
    import -m "Re-import of Blender CVS 2006/06/10" \
    soc-blender BLENDER_DIST BLENDER_CVS_2006_06_10