Subsections
There are not many requirements put on us developers with respect to
subversion usage, so we should
actually be able to follow them. If you feel that any of these rules
are stupid and as such should be changed, feel free do discuss them at
our group meetings. However, until we agree on changing rules, we
must obey them.
Before you make a commit to the trunk, you must make sure that all
scripts, compilations, regression tests, documentation generations, or
whatever needed in the project works as expected. There is nothing
more frustrating than running into someone else's problems when you are
about to solve that memory leak you have been looking for since 2pm
yesterday. One way to make sure that your last commit did not break
things is to actually have another pristine checkout of the
project. This pristine working copy should only be updated against the
repository for testing after your latest commit. If all checks
run okay in this pristine tree you probably did a proper commit from
your development working copy.
If you feel that you cannot fulfil this requirement there are two
options. i) Create a private branch, fix whatever you are doing, and
merge the changes into the main trunk when everything works again. ii)
Ask the rest of the development team's permission to leave this rule for
a very short time.
If you must check in personal debug code, create your own branch and
keep this branch and the main trunk in sync (see
Appendix 1.1 on how to do this).
Make sure that you stay up to date with the repository, i.e., commit
often and remember to issue svn update.
When you decide to make a commit, make it small and to the point. By
this we mean that commits should only contain whatever was needed to
solve a problem or to add a feature. There is no use in committing
trivial unnecessary changes into the repository such as stray blank
lines or extra white space characters in the end of a line (CR - CRLF
conversions are especially annoying and can be avoided by proper setup
of your subversion environment).
Log messages are useful for other developers when they want to know
what was done in a commit. You may think that trivial changes can
easily be “diffed” and thus need no log message. However, diffs
requires more work than reading log messages, and remember, log
messages for trivial changes are easy to write.
For projects that use
trac
for
software project management there is a possibility to close or add
comments to trac tickets directly when committing changes to the
repository. This is done by writing a properly formatted log message,
cf. A.20.
Cut and paste the configuration setup from
Appendix F into your subversion configuration
file $(HOME)/.subversion/config
For all text files we modify and maintain, we must add $Id$ near the
top of the file for easy identification of the file and its latest
revision change. If you set up a proper subversion configuration file
this requirement becomes trivial. The only thing needed then is to add
$Id$ into source files.
This should not need to be a rule, but ... There are a few concepts
which you may have neglected previously such as branches.
Read the branches section in the introduction and make sure you
understand it. If you get confused, ask someone. Note that our release
and branching procedure is defined in the branching section.
In order to make future branching of projects under subversion control
seamless, one must plan ahead when creating the project
repository. In subversion this means that a proper project directory
structure must be set up at the initial import of a project into
subversion control.
The directory structure adopted for the project must always contain
these three directories at root level
/trunk
/branches
/tags
The trunk directory holds the “main line” of
development, the branches directory contain branch copies, and
the tags directory contain tag copies.
This structure is needed for the branching procedure we are adopting
(cf. Appendix 1.1), and the recommended structure in the
subversion book.
2.1.9 Do not mess with the tags directory
Never make commits in the tag directory, it exists only for keeping
track of tags7.