One of the key strengths of Subversion is its documentation. Version Control with Subversion (which we'll just refer to as the Subversion book from now on) is an excellent book which explains in detail how to use Subversion and also provides a good introduction to all the basic concepts of version control. Rather than trying to write our own explanations (and not doing as good a job) we will simply refer you to the Subversion book, where appropriate, for the relevant information.
In general, the approach taken in this section is to make sure that you first understand how to perform a particular action using the Subversion tools and then describe how this differs using FCM.
In order to use FCM you need to have a basic understanding of version control. If you're not already familiar with Subversion or CVS then please read the chapter Fundamental Concepts from the Subversion book. In particular, make sure that you understand:
Copy-Modify-Mergeapproach to file sharing.
Note that this chapter states that 
  working copies do not always correspond to any single revision in the
  repository
. However, the FCM working practices do not encourage this and
  the wrapper scripts provided by FCM should ensure that your working copy (a
  local copy of the repository's files and directories where you can prepare
  changes) always corresponds to exactly one revision.
CVS users should already be familiar with all the basic concepts. This is not surprising since Subversion was designed as a replacement for CVS and it uses the same development model. However, there are some important differences which may confuse those more familiar with CVS. Fortunately, the appendix in the Subversion book Subversion for CVS Users is specifically written for those moving from CVS to Subversion and you should read this if you are a CVS user.
Before we discuss the FCM system you need to have a good understanding of how to perform most of the normal day-to-day tasks using Subversion. Therefore, unless you are already familiar with Subversion, please read the chapter Basic Usage from the Subversion book.
So, now you have an understanding of how to do basic tasks using
  Subversion (you did read the Basic Usage chapter didn't you?),
  how is using FCM different? Well, the key thing to remember is that, instead
  of using the command svn you need to use the command
  fcm. The advantages of this are as follows:
fcm implements all of the commands that svn
    does (including all the command abbreviations).fcm does very little and basically passes on
    the command to svn.fcm has a lot of additional functionality
    compared with the equivalent svn command.fcm also implements several commands not provided by
    svn.fcm provides support for URL and revision keywords.Full details of all the fcm commands available are provided
  in the FCM Command Reference section.
URL keywords can be used to specify URLs in fcm commands. The
  syntax is fcm:<keyword>. Keywords can be defined in the
  FCM keyword configuration file (i.e. $FCM/etc/fcm/keyword.cfg
  and $HOME/.metomi/fcm/keyword.cfg).
For example, if you define a keyword in your configuration file as follows:
location{primary}[um] = svn://fcm2/UM_svn/UM
  then you can abbreviate the URL as in the following examples:
# fcm ls svn://fcm2/UM_svn/UM fcm ls fcm:um # fcm ls svn://fcm2/UM_svn/UM/trunk fcm ls fcm:um_tr # OR: fcm ls fcm:um-tr # fcm ls svn://fcm2/UM_svn/UM/branches fcm ls fcm:um_br # OR: fcm ls fcm:um-br # fcm ls svn://fcm2/UM_svn/UM/tags fcm ls fcm:um_tg # OR: fcm ls fcm:um-tg
Using URL keywords has two advantages.
fcm
    switch --relocate command).In a similar way, revision keywords can be used to specify revision
  numbers in fcm commands. The keyword can be used anywhere a
  revision number can be used. Each keyword is associated with a URL keyword
  and can only be used when referring to that repository.
For example, if you define a keyword in your configuration file as follows:
revision[fcm:vn1.0] = 112
then the following commands are equivalent:
  fcm log -r 112 svn://fcm1/FCM_svn/trunk
  fcm log -r vn1.0 fcm:fcm_tr
You can use the fcm keyword-print command to print all
  registered location keywords. You can also print the location keyword and the
  revision keywords of a particular project. For example, to print the keywords
  for the UM project, you can type fcm keyword-print
  fcm:um.
Code differences can be displayed graphically using xxdiff by
  using the --graphical (or -g) option to fcm
  diff. This option can be used in combination with any other options
  which are accepted by svn diff.
An example display from xxdiff is shown below.

  xxdiff 2-way display
Points to note:
xxdiff is configured to show horizontal
    differences. This means that the parts of the line which have changed are
    highlighted (e.g. the text useful is highlighted in the
    example above).xxdiff to
    examine changes, you can define the graphic-diff setting in a
    FCM external configuration file (i.e.$FCM/etc/fcm/external.cfg
    or $HOME/.metomi/fcm/external.cfg). For example, to use 
      tkdiff, you can do:
      # in your site's $FCM/etc/fcm/external.cfg: # OR: in your $HOME/.metomi/fcm/external.cfg: graphic-diff = tkdiff
Your working copy may contain files or directories in conflict as a result of an update or a merge (covered later). Conflicts arise from the situation where two changes being applied to a file overlap. These can be text-based, as in two changes to the same line of text in a file, or filesystem-based, as in two different renamings of the same file.
For conflicts in normal (text) files, the command fcm
  conflicts can be used to help resolve them. (A discussion on binary
  files is given in the section Working
  with Binary Files later in this document.). For each file in text
  conflict, the fcm conflicts command calls a graphical merge
  tool (i.e. xxdiff by default) to display a 3-way diff.
An example display from xxdiff is shown below.

  xxdiff 3-way display
Points to note:
xxdiff is configured to automatically select regions that
    would end up being selected by an automatic merge (e.g. there are only
    changes in one of the files). Any difference hunks which cannot be
    resolved automatically are left unselected.If you just want to exit without making any decisions you can also just close the window.
xxdiff users
    manual (available from the Help menu). In particular, read
    the section 
    Merging files and resolving conflicts.If you have resolved all the conflicts in a file then you will be prompted
  on whether to run svn resolved on the file to signal that the
  file is no longer in conflict.
(SHELL PROMPT)$ fcm conflicts Conflicts in file: Gen_setup_local1.proc You have chosen to ACCEPT all the changes Would you like to run "svn resolved"? Enter "y" or "n" (or just press <return> for "n"): y Resolved conflicted state of 'Gen_setup_local1.proc' Conflicts in file: Gen_setup_remote2.proc Merge conflicts were not all resolved Conflicts in file: Gen_setup_remote3.proc All merge conflicts resolved Would you like to run "svn resolved"? Enter "y" or "n" (or just press <return> for "n"): y Resolved conflicted state of 'Gen_setup_remote3.proc'
It is important to realise that there are some types of merge that
  xxdiff will not be able to help you with.
xxdiff display will be extremely
    colourful and not very helpful.For files in tree conflict, which is otherwise known as a
  structural or filesystem-based conflict, the command fcm
  conflicts will manually resolve the problem by prompting you to choose
  a course of action. You can either keep the file as it was before the merge
  (keep local), or accept the external changes to the file.
The most common way to generate a tree conflict after a merge is when a file has been deleted or renamed on one branch, and modified on another. These are incompatible changes, to Subversion, and it doesn't know which action to take. This is the cause of the tree conflict dilemma which the user must solve.
In the following example, the branch in the working copy has had a deletion of a file. The branch that is being merged in has subsequently modified the file, which means that you may want to incorporate these changes. A tree conflict is therefore flagged up.
(SHELL PROMPT)$ fcm merge fcm:tutorial_br/dev/bfitz/r1_366
Merge(s) available from /tutorial/branches/dev/bfitz/r1_366: 1257
About to merge in changes from /tutorial/branches/dev/bfitz/r1_366@1257 compared with /tutorial/trunk@1
This merge will result in the following change:
--------------------------------------------------------------------------------
--- Merging r2 through r1257 into '.':
   C src/subroutine/hello_sub.f90
Summary of conflicts:
  Tree conflicts: 1
--------------------------------------------------------------------------------
Would you like to go ahead with the merge?
Enter "y" or "n" (or just press <return> for "n"): y
Performing merge ...
--- Merging r2 through r1257 into '.':
   C src/subroutine/hello_sub.f90
Summary of conflicts:
  Tree conflicts: 1
(SHELL PROMPT)$ fcm status
 M      .
!     C src/subroutine/hello_sub.f90
      >   local missing, incoming edit upon merge
(SHELL PROMPT)$ fcm info src/subroutine/hello_sub.f90
Path: src/subroutine/hello_sub.f90
Name: hello_sub.f90
Node Kind: none
Tree conflict: local missing, incoming edit upon merge
  Source  left: (file) svn://fcm1/tutorial_svn/tutorial/trunk/src/subroutine/hello_sub.f90@1
  Source right: (file) svn://fcm1/tutorial_svn/tutorial/branches/dev/bfitz/r1_366/src/subroutine/hello_sub.f90@1257
  In this example, running fcm conflicts would give:
(SHELL PROMPT)$ fcm conflicts [info] src/subroutine/hello_sub.f90: in tree conflict. Locally: deleted Externally: modified. Answer (y) to leave the file deleted. Answer (n) to add the file with the changes. Keep the local version? Enter "y" or "n" (or just press <return> for "n")
In this example, to keep the file as it was before (in a deleted state), enter y.
Otherwise, to accept the merge branch version of the file (adding it with the edited changes), enter n.
There are many other types of tree conflicts that can occur, and fcm
  conflicts does not cover all of them. Tree conflicts arising from
  updates and switches are not covered (which should be rare under FCM working
  practice). More importantly, tree conflicts on directories are not covered,
  because of the potential nesting of conflicts within the directories. It can
  often be difficult to identify the problem and figure out the solution in the
  case of directory conflicts, and the easiest solution may be to try to
  resolve the discrepancy before the merge.
For further details, see the Tree Conflict annex
If your working copy contains files which are not under version control
  then you can use the command fcm add --check to add them. This
  will go through each of the files and prompt to see if you wish to put that
  file under version control using svn add. For each file you can
  enter y for yes, n for no or a to assume yes
  for all following files.
(SHELL PROMPT)$ fcm add -c ? xxdiff1.png ? xxdiff2.png ? xxdiff3.png ? xxdiff4.png Add file 'xxdiff1.png'? Enter "y", "n" or "a" (or just press <return> for "n"): y A xxdiff1.png Add file 'xxdiff2.png'? Enter "y", "n" or "a" (or just press <return> for "n"): n Add file 'xxdiff3.png'? Enter "y", "n" or "a" (or just press <return> for "n"): a A xxdiff3.png A xxdiff4.png
Similarly, if your working copy contains files which are missing (i.e. you
  have deleted them without using svn delete) then you can use the
  command fcm delete --check to delete them. This will go through
  each of the files and prompt to see if you wish to remove that file from
  version control using svn delete.
As noted in the Subversion FAQ, it can be dangerous using these commands. If you have moved or copied a file then simply adding them would cause the history to be lost. Therefore take care to only use these commands on files which really are new or deleted.
The command fcm commit should be used for committing changes
  back to the repository. It differs from the svn commit command
  in a number of important ways:
fcm commit
    will abort if it finds that any files are out of date with respect to the
    repository. This ensures that your working copy reflects how the repository
    will be after you have committed your changes.
      fcm commit is not suitable if you need to commit
        changes from a working copy containing mixed revisions. However, you
        are very unlikely to need to do this.fcm branch-info command.fcm commit --dry-run to allow you to
        edit the commit message without committing any changes.fcm
        status).fcm commit command from a sub-directory of your working copy
    then it will automatically work out the top directory and work from there.
      svn update after the commit to ensure that your
    working copy is at the latest revision and to avoid any confusion caused by
    your working copy containing mixed revisions.(SHELL PROMPT)$ fcm commit Starting editor to create commit message ... Change summary: ------------------------------------------------------------------------ [Project: GEN] [Branch : branches/test/frsn/r123_foo_bar] [Sub-dir: <top>] M src/code/GenMod_Control/GenMod_Control.f90 M src/code/GenMod_Control/Gen_SetupControl.f90 ------------------------------------------------------------------------ Commit message is as follows: ------------------------------------------------------------------------ An example commit. ------------------------------------------------------------------------ Would you like to commit this change? Enter "y" or "n" (or just press <return> for "n"): y Sending src/code/GenMod_Control/GenMod_Control.f90 Sending src/code/GenMod_Control/Gen_SetupControl.f90 Transmitting file data .. Committed revision 170. => svn update At revision 170.
Branching is a fundamental concept common to most version control systems. For a good introduction please read the chapter Branching and Merging from the Subversion book. Even if you are already familiar with branching using other version control systems you should still read this chapter to see how branching is implemented in Subversion.
Having read this chapter from the Subversion book you should understand:
fcm (Subversion recommends it but doesn't insist on it).cheap- they are quick to create and take very little space.
FCM provides various commands which make working with branches easier (as described in the following sections).
The command fcm branch-create (or simply fcm
  bcreate or even fcm bc) should be used for creating new
  branches. It provides a number of features:
--branch-of-branch option if you need
        to create a branch of a branch. A branch of a branch can be useful in
        many situations. For example, consider a shared branch used by several
        members of your team to develop, say, a new science scheme, and you
        have come up with some different ideas of implementing the scheme. You
        may want to create a branch of the shared branch to develop your idea
        before merging it back to the shared branch. Note that you can only
        merge a branch of a branch with it's parent or with another branch
        created from the same parent. You can't, for example, merge it with the
        trunk.fcm bc NAME SOURCE@REV if you
        need to create a branch from an earlier revision of the SOURCE.--ticket
    <number> option, it is added to the commit log message. If you
    need to add anything to the commit log message, please do so
    above the line that says --Add your commit message
    ABOVE - do not alter this line or those below--.The following is a list of the different types of branches available:
(SHELL PROMPT)$ fcm bcreate -k 23 my_test_branch fcm:test Starting nedit to create commit message ... Change summary: ------------------------------------------------------------------------ A svn://fcm1/repos/OPS/branches/dev/frsn/r118_my_test_branch ------------------------------------------------------------------------ Commit message is as follows: ------------------------------------------------------------------------ Create an example branch to demonstrate branch creation for the user guide. #23: Created /OPS/branches/dev/frsn/r118_my_test_branch from /OPS/trunk@118. ------------------------------------------------------------------------ Would you like to go ahead and create this branch? Enter "y" or "n" (or just press <return> for "n"): y Creating branch svn://fcm1/repos/OPS/branches/dev/frsn/r118_my_test_branch ... Committed revision 169.
The command fcm branch-list (or simply fcm bls)
  can be used to list the branches you have created at the HEAD of a
  repository. If you specify the --user <userid> option, the
  branches created by <userid> are listed instead. You can specify
  multiple users with multiple --user <userid> options, or
  with a colon (:) separated list to a single --user
  <userid:list> option. Note that you can also list shared
  branches by specifying <userid> as Share, configuration
  branches by specifying <userid> as Config and release
  branches by specifying <userid> as Rel. The command
  returns 0 (success) if one or more branches is found for the specified users,
  or 1 (failure) if no branch is found.
(SHELL PROMPT)$ fcm branch-list fcm:gen 1 branch found for frsn in svn://fcm1/GEN_svn/GEN fcm:GEN-br/dev/frsn/r1191_clean_up/ (SHELL PROMPT)$ echo $? 0 (SHELL PROMPT)$ fcm branch-list --user frbj --user frsn fcm:gen 2 branches found for frbj, frsn in svn://fcm1/GEN_svn/GEN fcm:GEN-br/dev/frbj/r1177_gen_ui_for_scs/ fcm:GEN-br/dev/frsn/r1191_clean_up/ (SHELL PROMPT)$ echo $? 0 (SHELL PROMPT)$ fcm branch-list --user frva fcm:gen 0 branch found for frva in svn://fcm1/GEN_svn/GEN (SHELL PROMPT)$ echo $? 1
The command fcm branch-info (or simply fcm
  binfo) can be used to get various information about a branch. In
  particular, it summarises information about merges to and from the branch and
  its parent.
(SHELL PROMPT)$ fcm branch-info URL: svn://fcm1/FCM_svn/FCM/branches/dev/frsn/r1346_merge Repository Root: svn://fcm1/FCM_svn Revision: 1385 Last Changed Author: frsn Last Changed Rev: 1385 Last Changed Date: 2006-04-20 11:08:45 +0100 (Thu, 20 Apr 2006) -------------------------------------------------------------------------------- Branch Create Author: frsn Branch Create Rev: 1354 Branch Create Date: 2006-04-04 14:27:47 +0100 (Tue, 04 Apr 2006) Branch Parent: svn://fcm1/FCM_svn/FCM/trunk@1346 Last Merge From Parent, Revision: 1444 Last Merge From Parent, Delta: /FCM/trunk@1439 cf. /FCM/trunk@1395 Merges Avail From Parent: 1445 Merges Avail Into Parent: 1453 1452 1449 1446 1444 1443 1441 1434 1397 1396 ...
If you need information on the current children of the branch, use the
  --show-children option of the fcm branch-info
  command. If you need information on recent merges to and from the branch and
  its siblings, use the --show-siblings option of the fcm
  branch-info command.
To find out what changes have been made on a branch relative to its parent
  you can use the command fcm branch-diff (or simply fcm
  bdi.
--graphical--trac--wikiThe command fcm switch can be used to switch your working
  copy to point to another branch. For example, if you have a working copy at
  $HOME/work, currently pointing to the trunk or a branch of a
  project at svn://fcm1/FCM_svn/FCM/trunk, you can switch the
  working copy to point to another branch of same project:
(Shell prompt)$ cd $HOME/work (Shell prompt)$ fcm sw dev/frsn/r959_blockdata -> svn switch --revision HEAD svn://fcm1/FCM_svn/FCM/branches/dev/frsn/r959_blockdata U doc/user_guide/getting_started.html U doc/user_guide/code_management.html U doc/user_guide/command_ref.html U src/lib/FCM1/SrcFile.pm U src/lib/FCM1/Util.pm U src/lib/FCM1/Build.pm U src/lib/FCM1/Cm.pm U src/lib/FCM1/SrcPackage.pm U src/bin/fcm_internal U src/bin/fcm_gui Updated to revision 1009.
Unlike svn switch, fcm switch does extra
  checking to ensure that your whole working copy is switched to the new branch
  at the correct level of sub-directory. In addition, you can specify only the
  branch part of the URL, such as trunk,
  branches/dev/fred/r1234_bob or even
  dev/fred/r1234_bob and the command will work out the full URL
  for you.
The command fcm branch-delete (or simply fcm
  bdel) can be used to delete branches which are no longer required.
  Before being asked to confirm that you want to delete the branch, you will
  first see the same output as from fcm branch-info. This allows
  you to check, for example, whether your branch is being used anywhere else or
  whether the latest changes on your branch have been merged to the trunk. You
  will be prompted to edit your commit log message. If you need to add anything
  to the commit log message, please do so above the line that
  says --Add your commit message ABOVE - do not alter this line or those
  below--.
As mentioned earlier, fcm has its own merge tracking solution
  which is optimised for our recommended working practice. The solution assumes
  the following:
Note that the term source branch and target branch referred to above can also mean the trunk.
To perform a merge, use the command fcm merge <source>.
  This includes a number of important features:
--non-interactive option), it reports what changes will result
    from performing the merge and checks that you wish to continue.--auto-log option is specified, it adds the log
        messages of the merged revisions as well as the standard template. This
        is particularly useful when a small change is prepared in a branch, and
        often the same commit log messages have to be repeated when the change is
        merged and committed to the trunk. The option does not work very well if
        the branch contains merges from another branch.(SHELL PROMPT)$ fcm merge trunk # merge changes from the trunk into the branch Eligible merge(s) from FCM/trunk: 1383 1375 Enter a revision (or just press <return> for "1383"): Merge: /FCM/trunk@1383 c.f.: /FCM/trunk@1371 -------------------------------------------------------------------------dry-run A doc/fortran_standards/index.html U src/lib/FCM1/ReposBranch.pm -------------------------------------------------------------------------dry-run Would you like to go ahead with the merge? Enter "y" or "n" (or just press <return> for "n"): y Merge succeeded.
So far, all the tools described have been command line tools. Many people will be happy with these but, for those who prefer it, there is also a simple Graphical User Interface (GUI).
To run the GUI simply issue the command fcm gui from the
  directory you want as your working directory.
The GUI consists of several sections:

  Example GUI screen with the Status commands selected
If you run a more complicated command, like fcm
  branch-create, which prompts for input then extra entry windows will
  pop up.

  Example GUI pop-up window
The commands available from the GUI should be self explanatory. A few points to note:
--non-interactive option).
      branch-create,
        branch-delete and commit commands, which
        support the --password option, you should specify your
        password in Other options and click Run again.
        For other commands, you should run the command in interactive mode on
        the command line. Use the command displayed in the GUI text window but
        remove the --non-interactive option.There is a limitation with Subversion which you should be aware of. The
  svn rename command is not a true rename/move operation, but is
  implemented as a copy and delete. As a result, if you rename an item in a
  branch, and later attempt to merge it back to the trunk, the operation may
  not be handled correctly by svn merge (see subversion issue
  898 for further details). Until such time as support for a true rename
 is
  implemented in Subversion, you should avoid renaming of files or directories
  unless you can ensure that no-one is working in parallel on the affected
  areas of the project.
Trac has a simple and intuitive web interface which is relatively easy to pick up. It also includes a User and Administration Guide which is full of helpful information (and is referred to extensively in this section).
Trac contains a menu bar at the top of each page (which we will refer to as the Trac menu). This provides access to all the main features.
Although different projects may choose their own rules, we expect that most systems will have Trac configured so that all the information is viewable by anyone. However, in order to make any changes you will need to login. This ensures that any changes are identified with the appropriate userid.
In the rest of this section it is assumed that you have logged in to Trac and are therefore able to make changes.
If you haven't yet got a Trac userid (which should be the same as the userid you use for committing changes to Subversion) then please contact your system manager.
A wiki enables documents to be written in a simple markup language using a web browser. See the Trac Guide for information on the Trac Wiki Engine. Make sure that you read the information provided on:
Whenever you are viewing a wiki page in Trac you should see several buttons at the bottom of the page:
At the top of each wiki page at the right hand side you can select Page History. This shows you the full history of each page with details of when each change was made, who made the change and what the changes were.
The Trac Browser is used to view the contents of your repository. To get to it just select Browse Source from the Trac menu. You can view directories and files at any version, see their revision histories and view changesets. Any wiki formatting in log messages is recognised and interpreted so you can easily link a changeset to a Trac ticket by using Trac Links.
The Trac issue database provides a way of tracking issues within a project (e.g. bug reports, feature requests, software support issues, project tasks). Within Trac an issue is often referred to as a Ticket.
Please refer to the Trac Guide for the following information:
Each ticket can be assigned to a milestone. The Trac Roadmap can then be used to provide a view on the ticket system. This can useful to see what changes went into a particular system release or what changes are outstanding before a milestone can be reached.
Please refer to the Trac Guide for further information on the Trac Roadmap.
The Trac Timeline allows you to list all the activity on a project over any given period. It can list: