Introduction
  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).
  Making Changes
  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
        change.
- 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
            changes.
- 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
    you.
      
        - The reviewer can use the command fcm branch-diff
        <branch_name>to examine all of the changes on the
        branch.
- 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.
Working Copies
  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
    working copy.
- If you have a large project then you may prefer to work on a sub-tree
    of your project.
      Pros: 
        - 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.
 Cons: 
        - 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
  a branch.
  
    - 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
      change. 
- 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
      trunk. 
- An older revision of the trunk
- 
      There are a number of reasons why you may need to do this. For
      example: 
        - You are using a stable version to act as your control
        data.
- You need to know that your baseline is well tested (e.g. scientific
        changes).
- 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
  trunk.
  
    - 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
    isolation
- Necessary if you need to make your change relative to a well tested
    release.
- Branch from the latest code but then prepare all your changes in
    isolation
- Necessary if you need a stable baseline for your control
    data.
- 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
  review:
  
    - 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
    review
- 
      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
        again.
- Merge in the new changes but don't insist on further testing or
        review.
          
            - In most cases any changes won't clash so there is little to
            worry about.
- 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
            reviewed.
 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.
 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
        earlier.
- Automate your testing as far as possible to speed up the
        process.
 
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
  developers.
  
    - 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
  deleting branches:
  
    - 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
  The 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
  a problem.
  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 fcm
  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
  copy.)
  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
?      document.doc.r100
?      document.doc.r101
C      document.doc
  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
M      document.doc
  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.
  Using Locking
  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.
  Subversion supports locking
 to
  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
    Subversion.
- 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
    addressing.
- 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
  your edits.
  There are two possible approaches to recording the changes to individual
  files:
  
    - 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
      collaborators). Cons: 
        - 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
        file.
 
- 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: 
 * working_practices.html:
   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
  trunk.
  Trac Tickets
  Creating Tickets
  There are two different approaches to using the issue tracker within
  Trac:
  
    - 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. 
Using Tickets
  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
        system release.
 
- 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:
    source:/OPS/branches/dev/frdm/r123_MyBranch@234
- 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.
Creating Packages
  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
  combine using fcm merge.
  
    - 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.
      
        - Currently, fcm mergewill not work unless this is
        true.
 
- If further changes are made on a branch you are using in a package then
    you can incorporate these changes into your package using fcm
    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.
The 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
  tested.
  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.