This is the first file you should be reading after you get your CVS account.
We'll assume you're basically familiar with CVS, but feel free to post
your questions in the development forum at phorum.org. Please have a look at 
http://cvsbook.red-bean.com/ for more detailed information on CVS.

Collaboration is a Good Thing(tm), and CVS lets us do this. Thus, following
some basic rules with regards to CVS usage will:

   a. Make everybody happier, especially those responsible for maintaining
      the CVS itself.
   b. Keep the changes consistently well documented and easily trackable.
   c. Prevent some of those 'Oops' moments.
   d. Increase the general level of good will on planet Earth.


Having said that, here are the organizational rules:

   1. Respect other people working on the project.

   2. Discuss any significant changes on the list or forum before committing. 

   3. If you "strongly disagree" about something another person did, don't
      start fighting publicly - take it up in private email.

   4. If you don't know how to do something, ask first!

   5. Test your changes before committing them. We mean it. Really.
	

The next few rules are more of a technical nature.

   1. DO NOT TOUCH ChangeLog! It is automagically updated from the commit
      messages every day. Woe be to those who attempt to mess with it.

   2. All news updates intended for public viewing, such as new features,
      bug fixes, improvements, etc., should go into the NEWS file. Also see
      the note below about automatically updating NEWS in your commit message.

   3. Do not commit multiple file and dump all messages in one commit. If you
      modified several unrelated files, commit each group separately and
      provide a nice commit message for each one. See example below.

   4. Do write your commit message in such a way that it makes sense even
      without the corresponding diff. One should be able to look at it, and
      immediately know what was modified. Definitely include the function name
      in the message as shown below.

   5. In your commit messages, keep each line shorter than 80 characters. And
      try to align your lines vertically, if they wrap. It looks bad otherwise.


The format of the commit messages is pretty simple.

If a line begins with #, it is taken to be a comment and will not appear
in the ChangeLog.  If the line begins with @, it will be redirected to the
NEWS file. Everything else goes into the ChangeLog.

It is important to note that if your comment or news logline spans multiple
lines, you have to put # or @ at the beginning of _every_ such line. Every 
entry in NEWS has to have a name after it, so if you did it with someone's 
help, put both your names there. Your name WILL NOT be automatically put
at the end of the NEWS entry - so, please provide it yourself.

Example. Say you modified two files, functions.php and mysql.php. 
In functions.php you added a new formatting-function and in mysql.php you
fixed a bug in a query.
Don't commit both of these at once. Commit them separately and try to 
make sure your commit messages look something like the following.

For functions.php:

@- Added new formatting-function that will print everything bold
@  if the user is not wanted (Bob)

For mysql.php:
Fixed query which messed up the read-page. (Bob)
# Man, that query was in there since the stone-age!

The lines above marked with @ will go into NEWS file automagically, and the
# lines will be omitted from the ChangeLog. Alternatively, you might want
to modify NEWS file directly and not use the @ lines.

If you fix some bugs, you should note the bug ID numbers in your
commit message. Bug ID should be prefixed by "#" for easier access to
bug report when developers are browsing CVS.

Example:

Fixed attachments-problem when logged in. Bug #14016

If you don't see your messages in ChangeLog and NEWS right away, don't worry!
These files are updated once a day, so your stuff will not show up until
somewhat later. Don't go adding stuff to NEWS by hand if you already put @
lines in the commit message.

#To receive daily updates to ChangeLog and NEWS, send a message to
#cvs-subscribe@phorum.org.

Happy hacking,

The Phorum Dev Team