This chapter provides an administration guide for managers of projects or systems which are using FCM.
Note that, where this section refers to the FCM team this applies only to Met Office users. Users at other sites will either need to refer to the equivalent team within their organisation or will need to perfom these tasks themselves.
In theory you can set up your repository to have any random layouts.
However, many fcm commands have to make assumptions on a set of
working practices in order to function. The easiest way is to go with the
default:
<root>
|
|-- <project 1>
| |
| |-- trunk
| |-- branches
| |-- tags
|
|-- <project 2>
| |
| |-- trunk
| |-- branches
| |-- tags
|
|-- ...
In the default layout, each project is a sub-directory under the repository
root. Each project has a trunk sub-directory, and optionally a
branches sub-directory and a tags sub-directory. The
main line of development of the project lives directly under the
trunk sub-directory. A branch lives 3 levels under the
branches sub-directory. A tag lives 1 level under the
tags sub-directory.
FCM allows you to customise the layout for each repository by adding an
fcm:layout property at the HEAD of root of the repository.
E.g.:
(shell prompt)$ fcm co -q -N svn://host/repos repos-root (shell prompt)$ cd repos-root (shell prompt)$ fcm pe fcm:layout .
The default settings are given in the following. In the editor started by
fcm pe, add these settings and modify the VALUE of each KEY=VALUE
pair.
depth-project =
depth-branch = 3
depth-tag = 1
dir-trunk = trunk
dir-branch = branches
dir-tag = tags
level-owner-branch = 2
level-owner-tag =
template-branch = {category}/{owner}/{name_prefix}{name}
template-tag =
The settings will become effective when you fcm commit them.
An empty VALUE denotes an undefined value. The meanings of the settings are
described below:
depth-projectdepth-branchdir-branch) expected to be used by the name of a branch. This
setting must be defined.depth-tagdir-tag) expected to be used by the name of a tag. This
setting must be defined.dir-trunkdir-branchdir-taglevel-owner-branchlevel-owner-tagtemplate-branchtemplate-tagYou will need to decide whether to use a single project tree for your system or whether to use multiple projects.
Advantages of a single project tree:
Disadvantages of a single project tree:
checkout and
status can become frustratingly slow if your working copy is
too large.One common approach is to split the admin type files (e.g. site configurations that are unrelated to the main release) into a separate project from the core system files. If you include any large data files under version control you may also want to use a separate project for them to avoid making your working copies very large when editing code.
Note that there is often no obvious right or wrong answer so you just have to make a decision and see how it works out. You can always re-arrange your repository in the future (although be aware that this will break any changes being prepared on branches at the time).
You also need to decide whether your system requires its own repository (or multiple repositories) or whether it can share with another system.
For simplicity, in most cases you will probably want your own repository for your system.
You will not normally want to have multiple repositories for a system. One exception may be if you are storing large data files where you might not want to keep all the old versions for ever. Removing old versions can't be done without changing all the revision numbers which would mess up all your code history and Trac tickets. Storing the large data files in a separate repository reduces the impact if you do decide to remove old versions in the future. One disadvantage of this approach is that, for the moment at least, Trac only handles one repository so you will need a separate Trac environment for the data files.
For further details please see the section Planning Your Repository Organization from the Subversion book.
Normally the FCM team will help you to set up your initial repository.
However, it is quite simple if you need to do it yourself. First you need to
issue the command svnadmin create /path/to/repos. This creates an
empty repository which is now ready to accept an initial import. To do so, you
should create a directory tree in a suitable location, and issue the fcm
project-create command. At the root of the repository should be the
project directories. Each project should then contain the trunk
sub-directory. The sub-directories branches and
tags are optional. You can import your source files to the
trunk after the project is created. For example, if your
directory tree is located at $HOME/foo, you will do the following
to import it to a new repository:
(SHELL PROMPT)$ svnadmin create FOO_svn (SHELL PROMPT)$ fcm project-create FOO file://$PWD/FOO_svn (SHELL PROMPT)$ fcm checkout file://$PWD/FOO_svn/FOO $HOME/svn-wc/foo (SHELL PROMPT)$ cd $HOME/svn-wc/foo (SHELL PROMPT)$ cp -r $HOME/foo/* . (SHELL PROMPT)$ fcm add * (SHELL PROMPT)$ fcm status (SHELL PROMPT)$ fcm commit
Note that the svnadmin command takes a PATH as an
argument, as opposed to a URL for the svn command.
For further details please see the section Planning Your Repository Organization from the Subversion book.
Restrictions such as preventing anonymous read access or restricting write access to the trunk to a limited set of users can be arranged if necessary.
The FCM team will organise the hosting of your repository. A number of facilities will be set up for you as standard.
Your repository will be set up on a central FCM server and access will be
provided via svnserve (which we use in preference to
Apache for performance reasons). The FCM team will advise you of
the URL, and put in place standard hook scripts and backup procedures.
Note that if you want to use a Subversion repository for your own
individual use there is no need to get the FCM team to host it. You can
simply create your repository and then use a file:// URL to
access it.
Normally the FCM team will set up your Trac environment for you. This section describes some things you may wish to be configured. This can be done when the Trac environment is set up or later if you are unsure what you will require at first.
You will not normally want to allow anonymous users to make changes to your Trac environment since this means that changes may not get identified with a userid. The FCM team will normally set up your Trac environment such that any authenticated users can make changes. Further restrictions such as restricting write access to named accounts or preventing anonymous read access can be arranged if necessary.
The system manager will normally be given TRAC_ADMIN privileges. This allows them to do additional things which normal users cannot do such as:
For further details please see the section Trac Permissions from the Trac documentation.
By default, each Trac environment is configured such that the owner and reporter and anyone on the CC list are notified whenever a change is made to a ticket. If system mangers wish to be notified of all ticket changes then this can also be configured. Alternatively, email notifications can be disabled if they are not wanted.
There are lots of other things that can be configured in your Trac environment such as:
For further details please see the sections The Trac Configuration File and The Trac Ticket System from the Trac documentation.
The FCM team will organise the hosting of your Trac environment. It will be set up on the same server that hosts your Subversion repository and access will be provided via a web server. The FCM team will advise you of the URL, and put in place the backup procedures.
When you set up a repository for a new project, you will normally want the FCM team to set up a URL keyword for it in the FCM central configuration file. The name of the project should be a short string containing only word characters.
Individual projects can store revision keywords using the Subversion
property fcm:revision at registered URLs. Using the UM as an
example: if UM is a registered URL keyword, you can add the
fcm:revision property at the head of the UM project by doing a
non-recursive checkout. E.g.:
(prompt)$ fcm co -q -N fcm:um um (prompt)$ fcm pe fcm:revision um
In the editor, add the following and fcm commit:
vn6.3 = 402 vn6.4 = 1396 vn6.5 = 2599 vn6.6 = 4913 vn7.0 = 6163
In a subsequent invocation of fcm, if a revision keyword is
specified for a URL in the UM namespace, the command will attempt to load it
from the fcm:revision property at the head of the UM project.
Revision keywords can also be defined in the FCM central configuration file
if you prefer.
If the project has an associated Trac browser, you can also declare browser URL mapping in the central configuration file. This allows FCM to associate the Subversion URL with a Trac browser URL. There is an automatic default for mapping URLs hosted by the FCM team at the Met Office. External users of FCM may want to adjust this default for their site.
To change the default browser URL mapping, you need to make some
browser.*[namespace] = value declarations in your site's
$FCM/etc/fcm/keyword.cfg file. There are 3 components to this
declaration: browser.comp-pat, browser.loc-tmpl and
browser.rev-tmpl. The browser.comp-pat is a regular
expression, which is used to separate the scheme-specific part of a version
control system URL into a number of components by capturing its substrings.
These components are then used to fill in the numbered fields in the
browser.loc-tmpl. The template should have one more field than the
number of components captured by browser.comp-pat. The last field
is used to place the revision, which is generated via the
browser.rev-tmpl. This template should have a single numbered
field for filling in the revision number. This is best demonstrated by an
example. Consider the declarations:
browser.comp-pat = (?msx-i:\A//([^/]+)/(.*)\z)
browser.loc-tmpl = http://{1}/intertrac/source:{2}{3}
browser.rev-tmpl = @{1}
If we have a Subversion URL svn://repos/path/to/a/file, the
browser.comp-pat will capture the components [repos,
path/to/a/file]. When this is applied to the
browser.loc-tmpl, {1} will be translated to
repos and {2} will be translated to
path/to/a/file. A revision is not given in this case, and so
{3} is inserted with an empty string. The result is
http://repos/intertrac/path/to/a/file. If the revision is
1357, the browser.rev-tmpl will be used to translate
it to @1357, which is then inserted to {3} of the
browser.loc-tmpl. The result is therefore
http://repos/intertrac/path/to/a/file@1357.
For more information on how to set up the keywords, please refer to Repository & Revision Keywords and the Annex: FCM Configuration File.
The fcm make command (for invoking the extract and build
systems) is very flexibile and can be used in lots of different ways. It is
therefore difficult to give specific advice explaining how to configure them.
However, based on experience with a number of systems, the following general
advice can be offered.
Probably the best advice is to look at what has already been set up for other systems. The FCM team can advise on the best systems to examine.
When you create a stable build you should keep a FCM Make configuration file that can reproduce the build. One easy way to do this is to create your build using the standard configuration files and the latest versions of the code. You can then save the configuration file which is created on success.
Sometimes it is useful to be able to access particular revisions of some
directories from a FCM repository without having to go via Subversion.
Typical examples are namelist or data files used as inputs to a program. The
fcm export-items command is designed to help with this. It can
be used to maintain a set of extracted version directories from a FCM
repository. The command has the following options:
--config-file=PATH, --file=PATH, -f
PATH--directory=PATH, -C PATH--newThe 1st argument SOURCE should be the URL of a branch in a Subversion repository with the standard FCM layout.
The configuration file should be in the deprecated FCM 1 configuration
format. The label in each entry should be a path relative to the source URL.
If the path ends in * then the path is expanded recursively and
any sub-directories containing regular files are added to the list of relative
paths to extract. The value may be empty, or it may be a list of space
separated conditions. Each condition is a conditional operator
(>, >=, <,
<=, == or !=) followed by a
revision number. The command uses the revision log to determine the revisions
at which the relative path has been updated in the source URL. If these
revisions also satisfy the conditions set by the user, they will be
considered in the export.
Example:
(SHELL PROMPT)$ cat >fcm-export-items.cfg <<EOF namelists/VerNL_AreaDefinition >1000 !=1234 namelists/VerNL_GRIBToPPCode >=600 <3000 namelists/VerNL_StationList elements/* >1000 EOF (SHELL PROMPT)$ fcm export-items fcm:ver_tr
N.B.
Some options on working practices and policies are defined in the chapter on Code Management Working Practices. Individual projects should document the approach they have adopted. In addition, each project may also need to define its own working practices and policies to suit its local need. For example each project may need to specify: