The previous chapter described how to use the various parts of the FCM
code management system. They also described aspects of working practices
which are enforced by the system. This section discusses other recommended
working practices. They are optional in the sense that you don't have to
follow them to use FCM. It is a matter for individual projects to decide
which working practices to adopt (although we expect most projects/systems
using FCM to adopt similar practices).
This sub-section gives an overview of the recommended approach for
preparing changes. Particular topics are discussed in more detail in later
sub-sections where appropriate.
The recommended process for making a change is as follows:
- Before work starts on any coding you should make sure that there is a
Trac ticket open which explains the purpose of the change.
- Make sure that you set the ticket milestone to indicate which
release of the system you are aiming to include your change in.
- Accept the ticket to indicate that you are working on the
- For further advice on using tickets see Trac
Tickets later in this section.
- Create a branch
- For very simple changes you may be happy to prepare your changes
directly on the trunk. For further details see When to Branch later in this section.
- Create your branch either from the latest revision or from a stable
release (see Where to Branch From later
in this section).
- Prepare your code changes on the branch
- Commit interim versions to your branch on a regular basis as you
develop your change. This makes it much easier to keep track of what
you're changing and to revert changes if necessary.
- You may wish to merge in changes from the trunk. For further
details see Merging From the Trunk
later in this section.
- Make sure that you always commit any local changes to your
branch before doing a merge. Otherwise it becomes impossible to
distinguish your changes from those you have merged in. It is also
impossible to revert the merge without losing your local
- Likewise, always commit the merge to your branch (after
resolving any conflicts) before making any further changes.
- Don't include unrelated changes. If you want to make some changes
which aren't really associated with your other changes then use a
separate ticket and branch for these changes.
- Once your changes are ready for review, update the Trac ticket to
record which revision of the branch is to be reviewed and assign the ticket
to your reviewer.
- If the reviewer is happy with the change then he/she should update the
ticket to record that the change is approved and assign the ticket back to
- The reviewer can use the command
<branch_name> to examine all of the changes on the
- If changes are necessary then these should be prepared and then the
ticket updated to refer to the new revision under review.
- Once the change is approved it can be merged back to the trunk
- If you have been merging the latest changes from the trunk onto
your branch then the merge should be automatic. If not you may have
conflicts to resolve.
- Make sure that each merge is a separate commit to the trunk. i.e.
Don't combine changes from several branches in one commit. This makes
it easier to reverse changes if necessary. It also makes the changeset
easier to understand.
- Make sure that you use a good log message to describe your change.
For further details see Commit Log Messages
later in this section.
- Once the changes are commited, update the ticket to refer to the
changeset. Then the ticket can be closed.
- Once you are finished with the branch it should be deleted.
Some points to consider regarding working copies:
- If the size of your project is small then you will probably find it
easiest to work with a complete copy of the project (either the trunk or
your branch). This means that you always have immediate access to all the
files and that you are always able to perform merges using your normal
- If you have a large project then you may prefer to work on a sub-tree
of your project.
- Subversion operations on your working copy are faster.
- Your working copies use up less disk space. Remember that you may
be working on several changes at once on separate branches so you may
wish to have several working copies.
- You cannot always perform merge operations in sub-trees (if the
changes which need to be merged include files outside of your
sub-tree). To handle this we suggest that if you need to perform a
merge using a complete copy of your project you check it out in your
$LOCALDATA area (local disk space which is not backed up) to
be used purely for doing the merge.
- You may find that your change involves more files than you
originally thought and that some of the files to be changed lie outside
of your working copy. You then have to make sure that you have
committed any changes before checking out a larger working copy.
Branching & Merging
When to Branch
If you are making a reasonably large change which will take more than a
hour or two to prepare then there are clear advantages to doing this work on
- You can commit intermediate versions to the branch.
- If you need to merge in changes from the trunk then you have a record
of your files prior to the merge.
- The version of the code which gets reviewed is recorded. If subsequent
changes are required then only those changes will need reviewing.
However, if you are only making a small change (maybe only one line)
should you create a branch for this? There are two possible approaches:
- Always Branch
ALL coding changes are prepared on branches.
Pros: Same process is followed in all cases.
Cons: The extra work required to create the branch and
merge it back to the trunk may seem unnecessary for a very small
- Branch When Needed
Small changes can be committed directly to the trunk (after testing
and code review).
Pros: Avoids the overhead of using branches.
Cons: Danger of underestimating the size of a change. What
you thought was a small change may turn out to be larger than you thought
(although you can always move it onto a branch if this happens).
This is a matter for project policy although, in general, we would
recommend the Branch When Needed approach.
Where to Branch From
When you create a new branch you have two choices for which revision to
create the branch from:
- The latest revision of the trunk
This is the preferred choice where possible. It minimised the chances
of conflicts when you need to incorporate your changes back onto the
- An older revision of the trunk
There are a number of reasons why you may need to do this. For
- You are using a stable version to act as your control
- You need to know that your baseline is well tested (e.g. scientific
- Your change may need to be merged with other changes relative to a
stable version for testing purposes or for use in a package (see
Creating Packages later in this section).
Merging From the Trunk
Once you've created your branch you need to decide whether you now work in
isolation or whether you periodically merge in the latest changes from the
- Regularly merging from the trunk minimises the work involved when you
are ready to merge back to the trunk. You deal with any merge issues as you
go along rather than all at the end (by which time your branch and the
trunk could have diverged significantly).
- One downside of merging from the trunk is that the baseline for your
changes is a moving target. This may not be what you want if you have some
control results that you have generated.
- Another downside of merging from the trunk is that it may introduce
bugs. Although any code on the trunk should have been tested and reviewed
it is unlikely to be as well tested as code from a stable release.
- Unless you originally created your branch from the latest revision of
the trunk it is unlikely that you are going to want to merge in changes
from the trunk. The exception to this is once your change is complete when
it may make sense to merge all the changes on the trunk into your branch as
a final step. This is discussed in Merging Back
to the Trunk below.
So, there are basically three methods of working:
- Branch from a stable version and prepare all your changes in
- Necessary if you need to make your change relative to a well tested
- Branch from the latest code but then prepare all your changes in
- Necessary if you need a stable baseline for your control
- Branch from the latest code and then update your branch from the trunk
on a regular basis
- This is considered best practice for parallel working and
should be used where possible.
Merging Back to the Trunk
Before merging your change back to the trunk you will need to test your
change and get it reviewed. There are two options for what code to test and
- Test and review your changes in isolation, then merge to the trunk and
deal with any conflicts
This may be the best method if:
- Your changes have already been tested against a stable baseline and
re-testing after merging would be impracticable.
- Your branch needs to be available for others to merge in its
changes in isolation.
- Merge in the latest code from the trunk before your final test and
This has the advantage that you are testing and reviewing the actual
code which will be committed to the trunk. However, it is possible that
other changes could get committed to the trunk whilst you are completing
your testing and review. There are several ways of dealing with this:
- Use locking to prevent it happening. The danger with this is that
you may prevent others from being able to get their change tested and
reviewed, hence inhibiting parallel devlopment.
- Insist that the change is re-tested and reviewed. The problem with
this is that there is no guarantee that the same thing won't happen
- Merge in the new changes but don't insist on further testing or
This is the recommended approach since it doesn't inhibit
parallel development and yet the chances of a bad change being
committed to the trunk are still very small.
- In most cases any changes won't clash so there is little to
- Where there are clashes then, in most cases, they will be
trivial with little danger of any side-effects.
- Where the clashes are significant then, in most cases, this
will be very obvious whilst you are resolving the conflicts. In
this case you should repeat the testing and get the updates
You should also consider what can be done to minimise the time taken
for testing and review.
- Try to keep your changes small by breaking them down where
possible. Smaller changes are easier and quicker to review. This also
helps to minimise merge problems by getting changes back onto the trunk
- Automate your testing as far as possible to speed up the
Most projects will require the developer who prepared the change to merge
it back to the trunk once it is complete. However, larger projects may wish
to consider restricting this to a number of experienced / trusted
- This makes it easier to control and prioritise the merges.
- It applies an extra level of quality control.
- It minimises the risk of mistakes being merged back on to the trunk by
less experienced developers
- Scientific developers can concentrate on the scientific work.
- One issue is that the person doing the merge to the trunk may need help
from the original developer to prepare a suitable log message.
When to Delete Branches
Once you are finished with your branch it is best to delete it to avoid
cluttering up the directory tree (remember that the branch and all its
history will still be available). There are two obvious approaches to
- Delete the branch as soon as it has been merged back to the trunk
(prior to closing any associated Trac ticket)
- This is the tidiest approach which minimises the chances of old
branches being left around.
- Delete the branch once a stable version of the system has been released
which incorporates your change
- If a bug is found in your change during integration testing then you
can prepare the fix on the original branch (without having to do any
additional work to restore the branch).
Working with Binary Files
fcm conflicts command and
xxdiff can only
help you resolve conflicts in text files. If you have binary files in your
repository you need to consider whether conflicts in these files would cause
Resolving Conflicts in Binary Files
Conflicts in some types of binary files can be resolved manually. When you
are satisfied that the conflicts are resolved, issue the
resolved command on the file to remove the conflict status. (You will
be prevented from committing if you have a conflicting file in your working
If you have a conflicting MS Office 2003+ document, you may be able to
take advantage of the Tools > Compare and Merge Documents
facility. Consider a working copy, which you have just updated from revision
100 to revision 101, and someone else has committed some changes to a file
doument.doc you are editing, you will get:
(SHELL PROMPT)$ fcm conflicts
Conflicts in file: document.doc
document.doc: ignoring binary file, please resolve conflicts manually.
(SHELL PROMPT)$ fcm status
=> svn st
Open document.doc.r101 with MS Word. In Tools >
Compare and Merge Documents..., open document.doc. You
will be in Track Changes mode automatically. Go through the document to
accept, reject or merge any changes. Save the document and exit MS Word when
you are ready. Finally, issue the
fcm resolved command to remove
the conflict status:
(SHELL PROMPT)$ fcm resolved document.doc
=> svn resolved document.doc
Resolved conflicted state of 'document.doc'
(SHELL PROMPT)$ fcm status
=> svn st
Another type of conflict that you may be able to resolve manually is where
the binary file is generated from another file which can be merged. For
instance, some people who use LaTeX also store a PDF version of the document
in the repository. In such cases it is easy to resolve the conflict by
re-generating the PDF file from the merged LaTeX file and then issuing the
fcm resolved command to remove the conflict status. Note that,
in this particular case, a better approach might be to automate the
generation of the PDF file outside of the repository.
For files with binary formats, such as artwork or sound, it is often
impossible to merge conflicting changes. In these situations, it is necessary
for users to take strict turns when changing the file in order to prevent
time wasted on changes that are ultimately discarded.
allow you to prevent other users from modifying a file while you are
preparing changes. For details please refer to the chapter Locking
from the Subversion book. Note that:
- FCM does not add any functionality to the locking commands provided by
- If you need to lock a file you must do this in a working copy of the
trunk. There is nothing to stop you preparing the changes in a branch
(maybe you want to prepare the change in combination with a number of other
changes which do not require locking). However, you must always remember to
lock the file in the trunk first to prevent other users from preparing
changes to the file in parallel.
- Locking isn't the only way of preventing conflicts with binary files.
If you only have a small project team and a small number of binary files
you may find it easier to use other methods of communication such as emails
or just talking to each other. Alternatively, you may have a working
practice that particular files are only modified by particular users.
Commit Log Messages
Certain guidelines should be adhered to when writing log messages for code
changes when committing to the trunk:
- Start with a link to the ticket that raises the issues you are
- Add a keyword to indicate the command/module affected by this change.
- Add a summary of the change.
- Use Trac wiki syntax that can be displayed nicely in plain text.
- E.g. #429: user guide: improve commit log guidelines.
If you realise that you have made a mistake in the commit log, you can
modify it by using the command
fcm propedit svn:log --revprop -r REV
TARGET. Take care since this is an unversioned
property so you run the risk of losing information if you aren't careful with
There are two possible approaches to recording the changes to individual
- Maintain history entries in file headers
Pros: You don't need access to the Subversion repository in
order to be able to view a files change history (e.g. external
- History entries will produce clashes whenever files are changed in
parallel (although these conflicts are trivial to resolve).
- Source files which are changed regularly can become cluttered with
very long history entries.
- It is not possible to include history entries in some types of
- Record which files have changed in the commit log message
The log message should name every modified file and explain why it was
changed. Make sure that the log message includes some sort of description
for every change. The value of the log becomes much less if developers
cannot rely on its completeness. Even if you've only changed comments,
note this in the message. For example:
Added guidelines for writing log messages.
If you make exactly the same change in several files, list all the
changed files in one entry. For example:
* code_management.html, system_admin.html, index.html:
Ran pages through tidy to fix HTML errors.
It shouldn't normally be necessary to include the full path in the
file name - just make sure it is clear which of the changed files you are
referring to. You can get a full list of the files changed using
fcm log -v.
When you're committing to your own branch then you can be much more
relaxed about log messages. Use whatever level of detail you find helpful.
However, if you follow similar guidelines then this will help when it comes
to preparing the log message when your change is merged back to the
There are two different approaches to using the issue tracker within
- All problems should be reported using Trac tickets
Pros: The issue tracker contains a full record of all the
problems reported and enhancements requested.
Cons: The issue tracker gets cluttered up with lots of
inappropriate tickets, (which can make it much harder to search the
issues and can slow down the response to simple issues).
- Duplicate tickets.
- Issues already discussed in the documentation.
- Problems which turn out to be unrelated to the system.
- Problems which are poorly described.
- Things which would be better solved by a quick conversation.
- A Trac ticket shouldn't be created until the issue has been agreed
Problems and issues should first be discussed with the project team /
system maintainers. Depending on the project, this could be via email, on
the newsgroups or through a quick chat over coffee.
Nothing is lost this way. Issues which are appropriate for the issue
tracker still get filed. It just happens slightly later, after initial
discussion has helped to clarify the best description for the issue.
This sub-section provides advice on the best way of using tickets:
- In general, mature systems will require that there is a Trac ticket
related to every changeset made to the trunk. However this doesn't mean
that there should be a separate ticket for each change.
- If a change is made to the trunk and then a bug is subsequently
found then, if this happens before the next release of the system, the
subsequent change can be recorded on the same ticket.
- There can often be changes which don't really affect the system
itself since they are just system administration details. One way of
dealing with this is to open a ticket for each release in which to
record all such miscellaneous changes. It will probably be acceptable
to review these changes after they have been committed, prior to the
- Whenever you refer to source files/directories in tickets, make sure
that you refer to particular revisions of the files. This ensures that the
links will work in the future, even if those files are no longer in the
latest revision. For example:
Changes now ready for review:
- For some types of information, simply appending to the ticket may not
be the best way of working. For example, design notes or test results may
be best recorded elsewhere, preferably in a wiki page. If using wiki pages
we recommend using a naming convention to identify the wiki page with the
associated ticket, for example:
Please refer to [wiki:ticket/123/Design design notes]
See separate [wiki:ticket/123/TestResults test results]
Note that the square brackets have to be used since a page name containing
numbers is not recognised automatically.
Sometimes you may need to combine the changes from several different
branches. For example:
- Your branch is just part of a larger change which needs to be tested in
its entirety before committing to the trunk.
- You have some diagnostic code stored on a branch which you want to
combine with another branch for testing purposes.
We refer to this as creating a package.
To create a package you simply create a new branch as normal. The
type should be a package or possibly a
configuration branch to help you distinguish it from your other
branches. You then simply merge in all of the branches that you want to
- The chance of conflicts will be reduced if the branches you are
combining have been created from the same point on the trunk. Your package
branch should also be created from the same point on the trunk.
fcm merge will not work unless this is
- If further changes are made on a branch you are using in a package then
you can incorporate these changes into your package using
merge. Note, however, that if you have a branch which is being used
in a package then you should avoid merging changes from the trunk into your
branch. If you do then it will be very difficult to get updates to your
branch merged into the package.
fcm branch-info command is very useful for maintaining
packages. It tells you all of the branches which have been merged into your
package and whether there are any more recent changes on those branches.
Preparing System Releases
There are two ways of preparing system releases:
- A system release is simply a particular revision of the trunk
In order to do this it will be necessary to restrict changes on the
trunk whilst the release is being prepared.
- Users can continue to develop changes not intended for inclusion in
this release on branches.
- This may be a problem if preparing the release takes too long.
- Create a release branch where the release is finalised
You then lose the ability to be able to branch from the release.
It may be harder to identify what changes have been made between
releases (since you can't simply look at all the changesets made between
two revisions of the trunk).
Rapid vs Staged Development Practices
Most of this section on working practices has focussed on projects/systems
which are quite mature. Such systems are likely to have regular releases and
will, for example, insist that all changes to the trunk are reviewed and
If your system is still undergoing rapid development and has not yet
reached any sort of formal release then you will probably want to adopt a
much more relaxed set of working practices. For example:
- Changes don't need to be reviewed.
- More changes will be committed to the trunk. Only very large changes
will be prepared on branches.
- No requirement to have a Trac ticket associated with each change.
We have tried to avoid building too many assumptions about working
practices into the FCM system. This gives projects the flexibility to decide
which working practices are appropriate for their system. Hopefully this
means that FCM can be used for large or small systems and for rapidly
evolving or very stable systems.