Phorum SVN Rules
================

This is the first file you should be reading after you get your SVN account.
We'll assume you're basically familiar with SVN, but feel free to post
your questions in the development forum at phorum.org.

For information on Phorum's SVN repository, please visit our website:
http://phorum.org/cgi-bin/trac.cgi/wiki/SVNPage

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

   a. Make everybody happier, especially those responsible for maintaining
      the SVN 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.

   6. Members of the core dev team have the final say.

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

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

   4. 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.  Everything else goes into the ChangeLog.

It is important to note that if your comment logline spans multiple
lines, you have to put # at the beginning of _every_ such line.

Another special prefix is MFB.  If you are commiting something to a branch
and to trunk, plese put MFB on the front of the trunk commit.  This will
keep the log line from showing up twice in the changelog.

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

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

The # lines will be omitted from the ChangeLog.

If you fix some bugs, you should note the ticket ID numbers in your
commit message. Ticket ID should be prefixed by "#" for easier access to
tickets when developers are browsing Trac.

Example:

Fixed attachments-problem when logged in. Ticket #14016

To receive daily updates of commits, ask one of the devs to add you to
the list.

Happy hacking,

The Phorum Dev Team


* large parts of this file were copied from the PHP Dev Team's
* CVS-RULES file. Thanks guys.

