Making Code Changes in UM FCM

Before proceeding ensure you have completed the Setting up and Running UM FCM Jobs sections of the tutorial.

Ticket creation

In this section you will learn how to:

  • Create a ticket corresponding to the code change you have planned
  • Assign the ticket to a project Milestone
  • Assign a developer to the change
  • Make some changes to the ticket
  • Accept a ticket
  • Query tickets using Trac filtering.

Creating a ticket

Firstly, in a separate browser window or tab navigate to this link:

This should take you to the UM 7.1 tutorial page held under Trac.

To create a new ticket, you need to login to Trac. Trac has a menu bar at the top:

<Insert diagram of menu bar here>

Click on login. Your Trac login name is your puma login name. The password was emailed to you in an email entitled "Your UM Trac username/password" and is NOT the same as your PUMA account password. Click 'Ok'. You should see the menu bar change: A message 'logged in as...' will have appeared as well as menu bar options to View Tickets, create a New Ticket and Browse Source.

Click on the 'New Ticket' option and a form entitled Create New ticket should appear. You should now fill in the following items:

  • Short Summary - A one line summary of the change.
  • Type - pick option 'Enhancement'
  • Full description - A free format field where you can use wiki formatting to make a more informative description of the change.
  • Priority - leave as default 'normal'
  • Component - select 'GENERAL'.
  • Milestone - select 'vn7.1 Training'
  • Version - select 7.1

A link to WikiFormatting help appears next to the Full description field. Take some time at this point to follow this link to learn how you can enhance your text description of the change. Note that you can click on the Preview button at any time to see what the results of your formatting will look like before saving the ticket!

Using the help, try and see if you can produce the following in the description field:


Hint: The answer is here!

Once you are happy click on the Create Ticket button.

Editing a ticket

You will notice that the information you just saved appears in a yellow box at the top of the ticket. If you want to change the ticket you can add new information in the Comment field (note that you cannot go back and change the original description as you need FCM admin privileges to do so).

You can change certain properties of the ticket (such as Priority, Milestone etc) in the Change Properties section of the ticket.

At this point the ticket has not been assigned to anyone. The default is to assign to the person who raised the ticket, but if you want to assign it to someone else, click on the reassign to option in the Action section and type in the userid of the developer here.

To assign the ticket to yourself, click on accept ticket

To save the changes click on the Submit changes button

Querying tickets

You should remember the number of your new ticket, as you will have to revisit it later.

In real work, it is often not practical to have to remember the numbers of all the tickets you have created. Trac provides a powerful custom query for searching a ticket. You can search for the ticket you have just created by clicking the View tickets link. You should see your ticket listed underneath a Custom Query heading. By default a filter by Owner is set to display all your tickets.

To add filtering on additional criteria, select from the Add filter drop down menu. This should display additional options to filter by. To remove a filtering criteria click on the '-' to the right of the filter. Also try grouping your results by different categories.

Once you have set up the search criteria, click on the Update button to display the new selection of tickets.

Try the following:

  • Select all currently open defects.
  • Select all tickets (open and closed) owned by ros
  • Select all open tickets relating to Reconfiguration.

In addition, you can search for your ticket using the keyword Search utility at the top right hand corner of each Trac page. (If you enter #<number> in the search box, it will take you directly to that ticket.) In the tutorial, however, it may be easiest if you simply leave the tutorial Trac system open, so that you do not have to login again when you come back to your ticket.


In this section you will learn to:

  • Create a branch using the FCM gui and command line
  • Checkout and change a working copy
  • Get information about your working copy and branch.
  • Commit changes to your branch
  • Resolve conflicts between branches

Creating a branch

Firstly create a new directory (e.g um_tutorial) in your $HOME directory on PUMA which will be your work area and cd here.

Using the FCM GUI to create a branch.

A basic FCM GUI was originally created as an interface to the command line functionality of FCM. However, most people find that for the majority of tasks in FCM it is actually simpler and quicker to use the command line so that is what we will generally use in this tutorial! One exception where the GUI makes life a bit simpler is for branch creation so that is what will be described in this section.

However, it is also possible to perform the same functions using the command line if that is what you prefer - the command line syntax for creating a branch is given at the end of this section.

Launch the GUI from the command line by typing fcm gui.

Once you have the FCM GUI open, click on Branch on the top menu bar of the GUI.

By default, the create radio button should be checked, but if it isn't then check this option. Set up your branch details as follows:

  • Enter fcm:um_tutorial for the URL of the tutorial repository.
  • Enter a short branch name. This must contain only alpha-numeric characters and/or underscores, e.g. tutorial.
  • In the Source revision field enter vn7.1
  • Leave branch type as the default dev. This will ensure the branch you create is a user development branch.
  • Leave the source type as trunk and leave the prefix option as normal.
  • Enter the related Trac ticket number for the ticket you created earlier.

Click on Run when you are ready.

You will be prompted to edit the message log file. A standard template is automatically supplied and pops up in your default text editor. However, if you want to add extra comment for the branch, please do so above the line that says "--This line will be ignored and those below will be inserted automatically--". When you are ready, save your change and exit the editor. Answer Yes when you are prompted to go ahead and create the branch.

Note on passwords: You do not need a password for write access to the tutorial repository, however, Subversion may expect one to be provided the first time you try to create a branch either using the GUI or via the command line. If branch creation fails in the GUI with an authentication error you will need to add --password "" in the Other options field and then re-run. When running branch creation on the command line, if prompted for a password, just press return and the process should complete successfully. Thereafter, you should be able to use the GUI or command line without specifying a password again..

In the output window at the bottom of the GUI, you should hopefully see that your branch has been created successfully.


The branch will have a URL (location in the repository) like this:


Selecting the prefix option normal prepends the revision of the trunk you have branched from to your branch name. Here, as we have used version labelling it is VN7.1. If you had entered a version number instead of a label FCM would have added rxxx where xxx is the revision number.

Take a note of the revision number the branch was created at, and the branch name, VN7.1_[branch_name].

You can see your branch from within Trac: Click on Browse Source on the Trac menu bar and then navigate through:


Command line syntax for creating a branch.

fcm branch -c -n <branch name> --revision vn7.1 -k <xx> fcm:um_tutorial`

Where -k xx is used to associate ticket number xx with the branch.

Making changes to a working copy

Checking out a working copy

You may have noticed that creating a branch does not create a source code tree that you can edit (working copy)! To do this you need to Checkout from your branch. Make sure you have changed to the working directory you created earlier as by default code is checked out to the current directory. To checkout a copy of the UM code type:

fcm checkout URL

Where URL is the url of your branch. This can be supplied in it's full form:


or by a shorter way:

fcm:um_tutorial_br/dev/[userid]/VN7.1_[branch name]


  • In the second form we have replaced the leading part of the Subversion URL svn://puma/UM_TUTORIAL_svn/UM/branches with the FCM repository keyword fcm:um_tutorial_br. Keywords are shortcuts to save you from having to type in the full URL.
  • As we have not specified a local directory PATH in the checkout command, it will create a working copy in your current working directory, using the basename of the URL you are checking out. For example, when you checkout the branch you have just created, the command should create the working copy in $PWD/VN7.1_[branch name]. Make a note of the location of your working copy, in case you forget where you have put it.
  • We are also not specifying a revision to checkout, so it will checkout the HEAD, i.e. the latest, revision.

Changing code

Back in the work area directory you created at the beginning of branch creation you should now see that a new directory has appeared and that it is named the same as your branch. This is your 'working copy'. cd into this directory and explore the code structure to familiarise yourself with how the UM 7.1 code is structured.

Now make some code changes! Use the following scenario to take you through the basic method of changing, adding and deleting files:

Making changes

  • Change to the "src/control/top_level/" sub-directory in your working copy.
  • Edit um_shell.F90, using your favourite editor
  • Go to the line that says WRITE(6,*) 'I am PE ',mype
  • Change: 'I am PE ' to 'Hello World PE '.
  • Go to the line that says write(6,*) 'Start of UM Job : ',
  • Change: 'Start of UM Job : ' to 'Start of UM Tutorial Job: '
  • Save your changes and exit the editor.

Adding a new file

  • Still in the src/control/top_level directory, add a new file with a subroutine in, called um_shell_sub.F90. Put some simple write statements in the subroutine: e.g. WRITE(6,*) 'I am in subroutine um_shell_sub'
  • Run fcm add on the command line, to let the repository know you're adding a new file at the next commit: Make sure you are still in src/control/top_level and then type
    fcm add um_shell_sub.F90
    at the command prompt.
  • Amend um_shell.F90 to call this new subroutine.
  • Ensure you put a comment line ! DEPENDS ON: um_shell_sub above the CALL statement to ensure the dependency on your new file is registered.

Deleting a file

  • In the src/control/top_level directory, you should see a file dummy.F90 which contains an empty subroutine
  • Run fcm delete on the command line, to let the repository know you want to remove this file from your branch: Make sure you are still in src/control/top_level and then type
    fcm delete dummy.F90

Getting information about changes to a working copy

All the changes you have made so far have not been committed - i.e. saved to your branch in the repository. It is possible to list these changes using the fcm status command. Firstly, make sure you cd back up to the top level of your working directory and then type:

fcm status

and you should see a list of files that have been changed.If you've followed the example scenario above you should see output similar to this:

ros@puma$ fcm status
=> svn status
M      src/control/top_level/um_shell.F90
D      src/control/top_level/dummy.F90
A      src/control/top_level/um_shell_sub.F90

Notice that each changed file is flagged with a letter that indicates what the change was: A for Added, D for Deleted and M for Modified.

Reverting an uncommitted change

At this point you can undo any changes before committing. Try the following so that you know how to restore a changed file:

  • Edit src/control/top_level/initial.F90 to make any change and then save it.
  • Run fcm status again to confirm it has been flagged as Modified.
  • Run fcm revert on the command line: Make sure you are still in src/control/top_level and then type fcm revert initial.F90
  • Re-run fcm status to see that the file is no longer modified.

Note that revert will undo ALL changes to a file relative to your branch. Therefore if you've made several uncommitted changes, revert will undo them all, not just the last one.

Committing Changes

The change in your working copy remains local until you commit it to the repository where it becomes permanent. If you are planning to make a large number of changes, you are encouraged to commit regularly to your branch at appropriate intervals. Make sure you are in the top level directory of the working copy and then type:

fcm commit

A text editor will appear to allow you to edit the commit message. You must add a commit message to describe your change above the line that says "--This line, and those below, will be ignored--". Your commit will fail if you do not enter a commit message. Make sure you provide meaningful commit messages (the ticket should give sufficient information for you to be able to do this) as these will show up in the revision logs and can be a useful source of information.


  • Put a link to the ticket that raises the issues you are addressing using a wiki syntax, e.g. #15. Putting this as the first item in the commit message means it will show very clearly under Trac what ticket the change relates to.
  • State the reason for the change.
  • List possible impacts to other users.
  • Use wiki syntax that can be displayed nicely in plain text.
  • State the code author's name.


  • Repeat what's already stated in the merge template, e.g. statements such as "merge my branch to the trunk" should be avoided.
  • List the files you have changed. This will already have been included in the commit log by FCM.
  • Use wiki syntax that cannot be displayed nicely in plain text.
  • Be vague. A commit message that just says Fix is insufficient!

Save your change and exit the editor. Answer y when you are prompted to confirm the commit.

If you've followed the example scenario above you should see output similar to this:

ros@puma$ fcm commit
Starting emacs to edit commit message ...
Commit message is as follows:
#28 Rosalyn Hatcher - Testing Code changes section of the tutorial
--This line, and those below, will be ignored--
[Project: UM]
[Branch : branches/dev/ros/VN7.1_example_branch]
[Sub-dir: <top>]

M      src/control/top_level/um_shell.F90
D      src/control/top_level/dummy.F90
A      src/control/top_level/um_shell_sub.F90
Would you like to commit this change?
Enter "y" or "n" (or just press <return> for "n"): y
Deleting       src/control/top_level/dummy.F90
Sending        src/control/top_level/um_shell.F90
Adding         src/control/top_level/um_shell_sub.F90
Transmitting file data ..
Committed revision 1224.
Performing update to make sure your working copy is at this new revision ...
At revision 1224.

Getting information about your branch

If you need to find out information about your (or other users') branches, you can use the fcm branch info command.

In the directory where you checked out the code, type:

fcm branch -info

You should see information about your branch revision, when it was last changed and the parent it was created from:

ros@puma$ fcm branch -info
URL: svn://puma/UM_TUTORIAL_svn/UM/branches/dev/ros/VN7.1_example_branch
Repository Root: svn://puma/UM_TUTORIAL_svn
Revision: 1224
Last Changed Author: ros
Last Changed Rev: 1224
Last Changed Date: 2009-04-27 16:27:52 +0100 (Mon, 27 Apr 2009)
Branch Create Author: ros
Branch Create Rev: 1223
Branch Create Date: 2009-04-27 15:45:53 +0100 (Mon, 27 Apr 2009)
Branch Parent: svn://puma/UM_TUTORIAL_svn/UM/trunk@1198
Merges Avail Into Parent: 1224

Testing that your branch works

Now you have made a branch you can use it in the UMUI job you created in the first section of the tutorial. Go back to the section where you added the URL of an existing branch to your job and add your branch in as well. You can use FCM keyword shortcuts to abbreviate the URL. For example:


can be written as:


Remember that /src needs to be added to the end of the branch name.

Save, Process and Submit the job to test your changes.

If you have followed the tutorial scenario so far you should find that your job fails during the fcm extract of code. In the extract output on PUMA (/home/$USERID/um_extracts/$RUNID/umbase/ext.out) you will see an error message like this:

ERROR: UM/control/top_level/um_shell.F90: merge - cannot resolve conflicts:

This is because the sample branch and your branch contain modifications to the same file (um_shell.F90) and so conflict. The default behaviour of fcm is to fail and force you to resolve the conflict. The next section explains options for doing this.

Resolving Conflicts

In real UM scenarios, there will be working practices for how conflicts are resolved. It is likely that package branches will be used to merge several developer branches together.

For the purposes of this tutorial we will resolve the conflict by incorporating the change from the other branch in to yours:

  • In the working copy directory, type fcm merge fcm:um_tutorial_br/dev/ros/um_shell1
  • You will be prompted to confirm the merge. Answer y to this.
  • The conflict with um_shell.F90 will be discovered and you will be prompted to select an option. Enter p to select postpone.
  • You should see that um_shell.F90 is flagged with the letter C, identifying it as a Conflict
ros@puma$ fcm merge fcm:um_tutorial_br/dev/ros/um_shell1
Available Merges From /UM/branches/dev/ros/um_shell1: 1226 1222
Please enter the revision you wish to merge from (or just press <return> for "1226"):
About to merge in changes from /UM/branches/dev/ros/um_shell1@1226 compared with /UM/trunk@1198
This merge will result in the following change:
C    src/control/top_level/um_shell.F90
Would you like to go ahead with the merge?
Enter "y" or "n" (or just press <return> for "n"): y
Performing merge ...
Conflict discovered in 'src/control/top_level/um_shell.F90'.
Select: (p) postpone, (df) diff-full, (e) edit,
        (h) help for more options: p
--- Merging r1199 through r1226 into '.':
C    src/control/top_level/um_shell.F90

In order to make the working copy / branch usable, the conflicts must be resolved. To run conflict resolution type:

fcm conflicts

FCM will now run the file editor / difference tool xxdiff and will show a 3 way display:

The file in the middle is the common ancestor from the merge (i.e. the version of code before either of the changes have been applied). The file on the left contains the changes from your branch and the file on the right is the file containing the changes which you are merging in.

xxdiff is configured to automatically select regions that would end up being selected by an automatic merge (i.e. the changes do not overlap). Any difference "hunks" which cannot be resolved automatically are left "unselected". The number of unresolved changes is shown in the top right hand corner of the xxdiff display, under the Help menu. In this case it should show 1.

To inspect the differences either scroll through the files using the scrollbars or use keyboard shortcuts n to go to the next difference, and p to go to the previous one.

If you have followed the tutorial scenario so far you should see that the changes to the header, "My PE" write statement and the addition of call to the new subroutine um_shell_sub have been selected automatically by xxdiff because they do not overlap. However, the changes to the other write statement haven't because they do overlap (they should be highlighted in a different colour to the changes that don't overlap)

To resolve this conflict, select your write statement "Start of UM Tutorial Job" change by clicking on the text in the file on the left to select it. You should see that the number of unresolved changes now drops to 0 and the selected text changes colour.

Now select Exit with MERGED from the xxdiff File menu. You will be prompted to run svn resolved so answer y to this.

It is important to remember that the merge command only applies changes to your working copy. Therefore, you must commit the change to your branch in order for it to become permanent in the repository. Before you do that though, it is a good idea to inspect the changes prior to committing.

You have already seen how to use fcm status to see which files have changed in a working copy. To see more details, you need to use fcm diff. In your working copy directory type:

fcm diff -g

You will get a 2 way diff between your working copy and your branch. Scroll down to check that the changes you require as a result of the previous merge are correct.

If you are happy, exit the diff and type fcm commit. You will be prompted to edit the commit log as before. However, you may notice that a standard template is already provided for you. In most cases, the standard message should be sufficient. However, if you want to add extra comment to the commit, please do so above the line that says "--This line will be ignored and those below will be inserted automatically--". This is useful, for example, if there were significant issues addressed in the merge. Answer y to confirm the commit.

Now return to your UMUI job and go to the FCM Configuration Optional Modifications panel.
Either remove the entry for the 'um_shell1' branch or set the Use Y/N column to N.

Now you have merged in the changes from this branch to your branch and resolved conflicts the 'um_shell1' branch is redundant. You should now be able to Save, Process and then Submit your job to verify that all the changes have been applied.

This section of the tutorial has given a very simple example of a conflict resolution. In practice it can be much less straightforward! A separate tutorial section dedicated to conflict resolution using likely examples from the UM has been created which you should work through prior to starting any real development work. See Resolving Conflicts in the UM FCM.

Viewing your changes in Trac

Making a change to your branch results in a changeset which is basically a record of the changes. One way of viewing the changeset you have just created is to click on Timeline in Trac. The Timeline view is a sequential record of all events in the repository. You should see changesets for your original commit to your branch and the subsequent commit after resolving the conflicts near the top. The changesets are numbered corresponding to the revision of your branch which would have been displayed in the GUI when you did a commit or branch info. To see all the details click on the line 'Changeset[xxx]...' relating to your changeset. Alternatively, if you enter the number of the changeset "[xxx]" into the search box at the top right, it will take you directly to the numbered changeset. Your changeset should look something like this:


Compiler and Machine overrides

In this section you will learn to:

  • Change the compile options for a single file
  • Override global compiler and linker flags

File specific compiler overrides

The equivalent of the comp_specific file holding standard deck specific overrides is now held in FCM as a config file. If you want to see what it looks like go to:

The most likely scenario is that you need to change one of these default declaration or define a new one.

In the UMUI panel SubModel Independent -> Comp and Mods -> User Override Files there is a table where user override files can be specified.

In the 'Running Jobs' section of the tutorial you created the file $HOME/umui_jobs/overrides/tutorial_file_ovrds on PUMA and added the line

bld::tool::fflags::UM::atmosphere::boundary_layer::sice_htf %fflags_all -O0

Which redefined the default optimisation for code file sice_htf from -O2 to -O0.

In this example we were only changing the value of the optimisation flag added on to the global %fflags_all declaration. If you needed to completely change the global declaration for file specific overrides you would respecify it completely in your overrides file as follows:

%fflags_all -i8 -r8 -I $(UMDIR)/gcom/pathscale/gcom3.0/include

Here we've removed the '-fno-second-underscore' option.

Machine overrides

At some point you may also need to change declarations at machine level. Examples of the types of things you might change here are global compiler and linker flags. Default machine declarations are held in a config file in FCM so have a look at this first:]

Global compiler flags are controlled by the value of %fflags64_mpp and linker flags by %ldflags64_mpp

Create a new text file $HOME/umui_jobs/overrides/tutorial_mach_ovrds on PUMA and add in the following lines:

%fflags64_mpp %fflags64_mpp -pg
%ldflags64_mpp %ldflags64_mpp -pg

Here we've redeclared the value of each variable to its current value and added on the -pg option.

One you have done this and saved the file, add the path and name of this override file 'User machine overrides' table on panel SubModel Independent -> Comp and Mods -> User Override Files. Redo the Save, Process and Submit steps in your UMUI job.

Check the bld.cfg file in $DATAW/cfg again to see that the values for tool:fflags and tool::ldflags have changed.

Documenting your change

All code changes will need documenting to some degree. For a small change with strictly limited impact, you can use your ticket. If documentation is more extensive, then a Trac wiki page should be used.

For real UM changes, the information required should include (but is not limited to)

  • A description of the purpose of the change
  • A description of what code is changed
  • Test results
  • A note of whether the change will lose bit-comparison with previous version if the science options remain unchanged.
  • UMUI/STASHmaster/ANCILmaster changes required
  • A note of any impact on memory use or runtimes
  • Any other information that may help reviewers or later users of the change

Add some documentation to your ticket

Go back to the Trac ticket you created for your code change and add some documentation as follows:

  • A description of the purpose of the change
  • A description of what code has changed
  • Test results (i.e. Did your job run? Were there any clashes to resolve?)
  • Any other information you want to add.

Preview and Submit your ticket to save the changes.

Add some documentation using a wiki page

The convention for naming wiki pages to be associated with tickets is "wiki:ticket/xxx", where xxx is the ticket number. To create a ticket wiki page, edit your ticket to add some text like the following

Also see wiki page wiki:ticket/xxx

If you preview the ticket you should see that the wiki link has a "?" at the end. This indicates a wiki page that doesn't exist yet. Submit your ticket and then click on the wiki link, Trac will allow you to create and edit the page. Either repeat your documentation here or add in some new text.

It's probably a good idea to also add a link back to the relevant ticket (by using #xxx) in this page to make navigation easier.

You can Preview and Submit this page, and then click on the ticket link to return back to your ticket.

Tidying up

In the 'live' UM development environment, once you have finished your code change and it has been tested and reviewed, your branch will be committed to the project shared package branch by the project owner or, if the changes are destined to the Met Office, to the NCAS shared package branch by a member of the NCAS-CMS team. Once this has been done and there are no problems, your branch is essentially redundant. If no other users are using this branch in their UMUI jobs it can be deleted.

For the purposes of this tutorial, the full process of review and commit to trunk won't be covered and you can now proceed to delete your branch. When you delete a branch, it becomes invisible from the HEAD revision, but will continue to exist in the repository, should you want to refer to it in the future.

List branches owned by you

If you forget what your branch is called and/or/what other branches you have created, you can get a listing of all the branches you have created in a project. To do this use the following command:

fcm branch --list URL

Where URL is the name of repository you want to search. In this case it would be fcm:um_tutorial.

Delete a branch

Make sure you are in the relevant working copy directory and type:

fcm branch -delete

You will be prompted to edit the commit message file. A standard template is automatically supplied for the commit. However, if you want to add extra comment for the branch, please do so above the line that says "--This line will be ignored and those below will be inserted automatically--". Save your change and exit the editor.

Answer y when you are prompted to go ahead and delete this branch.

Your working copy is now pointing to a branch that no longer exists at the HEAD revision of the repository. It is possible to keep this working copy, create a new branch and switch your working copy to point to the new branch. Otherwise, you can remove your working copy by issuing a careful rm -rf command.

Back in Trac, close your ticket as 'fixed' by clicking on the Resolve option button and saving the changes.

UM 7.1 Homepage
FCM User Guide
FCM Quick Reference

For queries / corrections / suggestion mail:


Last modified 10 years ago Last modified on 02/25/11 15:19:19