WORKING WITH CVS
----------------
$Id: CVS.txt 4503 2007-02-27 16:43:46Z wjpalenstijn $


This document is a short help on using CVS for getting GemRB
sources and contributing back to the project. This is very
basic and incomplete document - read CVS handbook for complete
documentation and take a look at 

  http://sourceforge.net/cvs/?group_id=10122.

GemRB repository can be viewed at 

  http://gemrb.cvs.sourceforge.net/ .



Getting GemRB from CVS:
-----------------------

If you do not have account on SourceForge.Net or you are not GemRB
developer, you will need to get GemRB from anonymous CVS. It lags
some time behind developer CVS, but mostly it's not a problem
(unless you need some fresh patch quickly :-)):

  export CVSROOT=:pserver:anonymous@gemrb.cvs.sourceforge.net:/cvsroot/gemrb

If you are a GemRB developer, specify this CVSROOT instead
(of course replace `username' with your own username):

  export CVSROOT=:ext:username@gemrb.cvs.sourceforge.net:/cvsroot/gemrb

Now do initial GemRB checkout:

  cvs -z3 checkout gemrb

GemRB will be put into gemrb/ subdir in your current directory.



Updating your working copy of GemRB:
------------------------------------

Now that you have made an initial checkout of GemRB, updating your
tree to current CVS version is easy:

  cd gemrb
  cvs -z3 update -Pd

You should see list of updated files and directories with letter
codes in front of each file line. They usually are:

  U or P - file has been Updated or Patched with new version from CVS
  M      - you have Modified the file locally
  C      - there's a Conflict in the file between CVS version 
           and your local modifications.
  A      - newly Added file, not yet committed
  ?      - unknown file, not in CVS


Comparing your tree to CVS repository:
--------------------------------------

Update your local tree to see which files you have changed.
To display difference between your and CVS versions of some files:

  cvs -z3 diff -pu file1 [file2 ...]


Sending patches:
----------------

If you are not GemRB developer, the best way you can contribute
your changes is by sending a patch with your changes.

Creating a patch:

  cvs -z3 diff -pu file1 [file2 ...] >john_new_avatars.diff

Create a bug report or patch submission on bug tracker and attach
the *.patch file to it. Same caveats as when committing your
work back to CVS apply - see paragraph `Committing your changes ...' below.


Committing your changes back into CVS:
--------------------------------------

You can't commit into GemRB CVS unless you are a GemRB developer.
If you are not, look into paragraph 'Sending Patches' instead.

If you are a developer, this is how you add your local modifications
into CVS repository:

  cvs commit file1 [file2 ....]

Where `file1', `file2', etc. are the files you have modified. 

Some caveats:

  - Always make sure GemRB compiles and works before committing.
    There's no such a thing as a bugfree-guaranteed one-line modification!!

  - Always do cvs update before committing into CVS

  - Commit only clean changes. It's good to review all your modifications
    before committing them to make sure you do not commit 
    debugging printf's, temporary hacks or orphaned functions.

  - Commit your work in small logically separated chunks.
    E.g. if you made two independent changes in different files, consider
    committing each one separately, giving each one meaningful description

  - Do not commit mere indentation and aesthetic fixes. It's really
    annoying to read two pages of useless changes.


Other modules in CVS:
---------------------
Apart from GemRB, there are other useful modules in CVS you can checkout.
Just use their name in cvs checkout command instead of gemrb

  cvs -z3 checkout <module>


Utilities/chitem - Avenger's DLTCEP, Windows app to view and edit
    IE data files. Probably the most complete IE viewer

Utilities/ielister

ie_shell - simple Python shell and modules to view IE files. Only few
    formats and only their PST versions are supported.

Win32 - files needed to build GemRB on Windows
