Guidelines

These guidelines are intended to provide a set of best practices for group development.
Various release policies have heavily influenced this document.

NOTE: Bridgepoint Education is referred to as: BPE

Start your day by updating your working copy

Before you start work, do an svn update. You will want to do an
svn diff on each file that you have modified, but not committed.
This will at least provide a clue to you that someone else is working on the
same source code that you are.

If there are differences, communicate with
the other contributor about merging differences.

Think Twice before Committing

Committing something to SVN has serious consequences. All other
developers will get your changes once they are in SVN, and if they
break something, they will break it for everybody. All commits will be
publicly available in the SVN repository forever.

On the other hand SVN allows one to revert changes, so it’s
possible to recover from mistakes. This is relatively easy for commits
to single files but it can also be a significant amount of work for
bigger changes.
The baseline is: Be aware of the consequences of your commits. Take
time to think about them before committing.

Never commit code that doesn’t compile

Compile the code and correct all errors before committing. Make sure
that newly added files are committed. If they are missing your local
compile will work fine but everybody else won’t be able to compile.

You certainly should make sure that the code compiles with your
local setup. You should also consider what consequences your commit
will have for compiling with the source directory being different from
the build directory.

Test your changes before committing

Start the application affected by your change and make sure that the changed code behaves as desired.

Run regression tests if available.

Double check what you commit

Do a svn update and a svn diff before committing. Take messages from SVN about conflicts, unknown files, etc. seriously. svn diff will tell you exactly what you will be committing. Check if that’s really what you intended to commit.

Always add descriptive log messages

Log messages should be understandable to someone who sees only the
log. They shouldn’t depend on information outside the context of the
commit. Try to put the log messages only to those files which are
really affected by the change described in the log message.

In particular put all important information which can’t be seen from the diff in the log message.

Honor BPE coding policies

TBD.

Respect commit policies set by the Release Plans

TBD.

Respect other developer’s code

Respect the policies of application and library maintainers, and consult with them before making large changes.

Source control systems are not a substitute for developer communication.

Announce changes in advance

When you plan to make changes which affect a lot of different code
in SVN, announce them on the mailing list in advance. For instance,
changes in libraries might break other code even if they look trivial,
e.g., because an application must also compile with older versions of
the librariy for some reasons. By announcing the changes in advance,
developers are prepared, and can express concerns before something gets
broken.

Code review by other developers

Don’t commit changes to the public API of libraries without prior
review by the project owner. Requiring a review for
these changes is intended to avoid problems for the users of the APIs
and to improve the quality of the APIs.

Take responsibilty for your commits

If your commit breaks something or has side effects on other code, take the responsibility to fix or help fix the problems.

Don’t commit code you don’t understand

Avoid things like “I don’t know why it crashes, but when I do this,
it does not crash anymore.” or “I’m not completely sure if thats right,
but at least it works for me.”.

If you don’t find a solution to a problem, discuss it with other developers.

Don’t commit if other developers disagree

If there are disagreements over code changes, these should be
resolved by discussing them on the mailing lists or in private, not by
forcing code on others by simply committing the changes to SVN.

Backport bugfixes

If you commit bugfixes, consider porting the fixes to other
branches. Use the same comment for both the original fix and the
backport, that way it is easy to see which fixes have been backported
already.

Use bug tracking system numbers

If you fix bugs reported on the bug tracking system, add the bug
number to the log message. In order to keep the bug tracking system in
sync with SVN, you should reference the bug report in your commits, and
close the fixed bugs in the bug tracking system.

This doesn’t mean that you don’t need an understandable log
message. It should be clear from the log message what has been changed
without looking at the bug report.

Tags and branches

There are rules for where to place release tags and branches in the
repository. Official branches and releases will be created by the
release coordinator in the branches/[branch name] and tags/[tag name] directories, scripts will ensure that this folders are protected.

Developers should place all branches which are aimed to be released in branches/appname and name them like the release, e.g. branches/appname/1.5. For all release tags, tags/appname is the right place.

All temporary working branches (which should be deleted again after the work has ended) should be located in branches/work
with some name describing both which part of BPE (or which application)
is branched and which work is done there. A good example would be branches/work/khtml-paged for a khtml working branch to include paged media support. Bad idea would be something like branches/work/make-it-cool.

Don’t add generated files to the repository

Files generated at build time shouldn’t be checked into the
repository because this is redundant information and might cause
conflicts. Only real source files should be in SVN. An exception to
that are files generated by tools that would be an unusual requirement
for building BPE.

Standard tools include: TBD

Tools which shouldn’t be a requirement for building BPE include: TBD

Don’t use SVN keywords in source files

SVN keywords like Id or Log cause unnecessary
conflicts when merging branches and don’t contain any information which
wouldn’t be available in the SVN repository anyway.

Make “atomic” commits

SVN has the ability to commit more than one file at a time.
Therefore, please commit all related changes in multiple files, even if
they span over multiple directories at the same time in the same
commit. This way, you ensure that SVN stays in a compilable state
before and after the commit.

Don’t mix formatting changes with code changes

Changing formatting like indenting or white spaces blows up the
diff, so that it is hard to find code changes if they are mixed with
reindenting commits or similar things when looking at the logs and
diffs later. Committing formatting changes separately solves this
problem.