New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
code_management.html in vendors/FCM-2017.10.0/doc/user_guide – NEMO

source: vendors/FCM-2017.10.0/doc/user_guide/code_management.html @ 13615

Last change on this file since 13615 was 10672, checked in by nicolasmartin, 5 years ago

Reimport latest FCM release
File size: 52.3 KB
Line 
1<!DOCTYPE html>
2<html>
3<head>
4  <title>FCM: User Guide: Code Management</title>
5  <meta name="author" content="FCM team" />
6  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7  <link rel="icon" href="../etc/fcm-icon.png" type="image/png" />
8  <link rel="shortcut icon" href="../etc/fcm-icon.png" type="image/png" />
9  <link href="../etc/bootstrap/css/bootstrap.min.css" rel="stylesheet" media="screen" />
10  <link href="../etc/fcm.css" rel="stylesheet" media="screen" />
11</head>
12<body>
13  <div class="navbar navbar-inverse">
14    <div class="container-fluid">
15      <div class="navbar-header">
16        <a class="navbar-brand" href=".."><span class="fcm-version">FCM</span></a>
17      </div>
18      <div class="collapse navbar-collapse">
19        <ul class="nav navbar-nav">
20          <li><a href="../installation/">Installation</a></li>
21
22          <li><a class="active" href="#">User Guide</a></li>
23        </ul>
24      </div>
25    </div>
26  </div>
27
28  <div class="page-header">
29    <div class="fcm-page-content pull-right well well-sm"></div>
30    <h1>FCM: User Guide: Code Management</h1>
31  </div>
32
33  <div class="container">
34  <div class="row">
35  <div class="col-md-12">
36
37  <h2 id="svn">Using Subversion</h2>
38
39  <p>One of the key strengths of Subversion is its documentation. <a href=
40  "http://svnbook.red-bean.com/en/1.8/">Version Control with Subversion</a>
41  (which we'll just refer to as the <cite>Subversion book</cite> from now on)
42  is an excellent book which explains in detail how to use Subversion and also
43  provides a good introduction to all the basic concepts of version control.
44  Rather than trying to write our own explanations (and not doing as good a
45  job) we will simply refer you to the <cite>Subversion book</cite>, where
46  appropriate, for the relevant information.</p>
47
48  <p>In general, the approach taken in this section is to make sure that you
49  first understand how to perform a particular action using the Subversion
50  tools and then describe how this differs using FCM.</p>
51
52  <h3 id="svn_concepts">Basic Concepts</h3>
53
54  <p>In order to use FCM you need to have a basic understanding of version
55  control. If you're not already familiar with Subversion or CVS then please
56  read the chapter <a href=
57  "http://svnbook.red-bean.com/en/1.8/svn.basic.html">Fundamental Concepts</a>
58  from the <cite>Subversion book</cite>. In particular, make sure that you
59  understand:</p>
60
61  <ul>
62    <li>The <q title=
63    "http://svnbook.red-bean.com/en/1.8/svn.basic.version-control-basics.html#svn.basic.vsn-models.copy-merge">
64    Copy-Modify-Merge</q> approach to file sharing.</li>
65
66    <li>Global Revision Numbers.</li>
67  </ul>
68
69  <p>Note that this chapter states that <q title=
70  "http://svnbook.red-bean.com/en/1.8/svn.basic.in-action.html#svn.basic.in-action.wc">
71  working copies do not always correspond to any single revision in the
72  repository</q>. However, the FCM working practices do not encourage this and
73  the wrapper scripts provided by FCM should ensure that your working copy (a
74  local copy of the repository's files and directories where you can prepare
75  changes) always corresponds to exactly one revision.</p>
76
77  <p><acronym title="Concurrent Versions System">CVS</acronym> users should
78  already be familiar with all the basic concepts. This is not surprising since
79  Subversion was designed as a replacement for CVS and it uses the same
80  development model. However, there are some important differences which may
81  confuse those more familiar with CVS. Fortunately, the appendix in the
82  <cite>Subversion book</cite> <a href=
83  "http://svnbook.red-bean.com/en/1.8/svn.forcvs.html">Subversion for CVS
84  Users</a> is specifically written for those moving from CVS to Subversion and
85  you should read this if you are a CVS user.</p>
86
87  <h3 id="svn_basic">Basic Command Line Usage</h3>
88
89  <p>Before we discuss the FCM system you need to have a good understanding of
90  how to perform most of the normal day-to-day tasks using Subversion.
91  Therefore, unless you are already familiar with Subversion, please read the
92  chapter <a href="http://svnbook.red-bean.com/en/1.8/svn.tour.html">Basic
93  Usage</a> from the <cite>Subversion book</cite>.</p>
94
95  <p>So, now you have an understanding of how to do basic tasks using
96  Subversion (you did read the <cite>Basic Usage</cite> chapter didn't you?),
97  how is using FCM different? Well, the key thing to remember is that, instead
98  of using the command <code>svn</code> you need to use the command
99  <code>fcm</code>. The advantages of this are as follows:</p>
100
101  <ul>
102    <li><code>fcm</code> implements all of the commands that <code>svn</code>
103    does (including all the command abbreviations).</li>
104
105    <li>In some cases <code>fcm</code> does very little and basically passes on
106    the command to <code>svn</code>.</li>
107
108    <li>In other cases <code>fcm</code> has a lot of additional functionality
109    compared with the equivalent <code>svn</code> command.</li>
110
111    <li><code>fcm</code> also implements several commands not provided by
112    <code>svn</code>.</li>
113
114    <li><code>fcm</code> provides support for URL and revision keywords.</li>
115
116    <li>Most of the additional features and commands are discussed later in
117    this section or in the following sections.</li>
118  </ul>
119
120  <p>Full details of all the <code>fcm</code> commands available are provided
121  in the <a href="command_ref.html">FCM Command Reference</a> section.</p>
122
123  <h4 id="svn_basic_keywords">URL And Revision Keywords</h4>
124
125  <p>URL keywords can be used to specify URLs in <code>fcm</code> commands. The
126  syntax is <code>fcm:&lt;keyword&gt;</code>. Keywords can be defined in the
127  FCM keyword configuration file (i.e. <samp>$FCM/etc/fcm/keyword.cfg</samp>
128  and <samp>$HOME/.metomi/fcm/keyword.cfg</samp>).</p>
129
130  <p>For example, if you define a keyword in your configuration file as
131  follows:</p>
132  <pre>
133location{primary}[um] = svn://fcm2/UM_svn/UM
134</pre>
135
136  <p>then you can abbreviate the URL as in the following examples:</p>
137  <pre>
138# fcm ls svn://fcm2/UM_svn/UM
139fcm ls fcm:um
140
141# fcm ls svn://fcm2/UM_svn/UM/trunk
142fcm ls fcm:um_tr  # OR: fcm ls fcm:um-tr
143
144# fcm ls svn://fcm2/UM_svn/UM/branches
145fcm ls fcm:um_br  # OR: fcm ls fcm:um-br
146
147# fcm ls svn://fcm2/UM_svn/UM/tags
148fcm ls fcm:um_tg  # OR: fcm ls fcm:um-tg
149</pre>
150
151  <p>Using URL keywords has two advantages.</p>
152
153  <ul>
154    <li>They are shorter and easier to remember.</li>
155
156    <li>If the repository needs to be moved then only the keyword definitions
157    need to be updated (although any working copies you have will still need to
158    be <em>relocated</em> by issuing a <a href=
159    "http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.switch.html"><code>fcm
160    switch --relocate</code></a> command).</li>
161  </ul>
162
163  <p>In a similar way, revision keywords can be used to specify revision
164  numbers in <code>fcm</code> commands. The keyword can be used anywhere a
165  revision number can be used. Each keyword is associated with a URL keyword
166  and can only be used when referring to that repository.</p>
167
168  <p>For example, if you define a keyword in your configuration file as
169  follows:</p>
170  <pre>
171revision[fcm:vn1.0] = 112
172</pre>
173
174  <p>then the following commands are equivalent:<br />
175  <code>fcm log -r 112 svn://fcm1/FCM_svn/trunk</code><br />
176  <code>fcm log -r vn1.0 fcm:fcm_tr</code></p>
177
178  <p>You can use the <code>fcm keyword-print</code> command to print all
179  registered location keywords. You can also print the location keyword and the
180  revision keywords of a particular project. For example, to print the keywords
181  for the <samp>UM</samp> project, you can type <code>fcm keyword-print
182  fcm:um</code>.</p>
183
184  <h4 id="svn_basic_diff">Examining Changes</h4>
185
186  <p>Code differences can be displayed graphically using <code>xxdiff</code> by
187  using the <code>--graphical</code> (or <code>-g</code>) option to <code>fcm
188  diff</code>. This option can be used in combination with any other options
189  which are accepted by <code>svn diff</code>.</p>
190
191  <p>An example display from <code>xxdiff</code> is shown below.</p>
192
193  <p class="image"><img src="xxdiff1.png" alt="xxdiff 2-way display" /><br />
194  <code>xxdiff</code> 2-way display</p>
195
196  <p>Points to note:</p>
197
198  <ul>
199    <li>By default <code>xxdiff</code> is configured to show horizontal
200    differences. This means that the parts of the line which have changed are
201    highlighted (e.g. the text <samp>useful</samp> is highlighted in the
202    example above).</li>
203
204    <li>The number shown to the right of each file name shows the current line
205    number. The number on the far right is the number of differences found (2
206    in the example above).</li>
207
208    <li>You may find the following keyboard shortcuts useful.
209
210      <ul>
211        <li><kbd>N</kbd> - move to the next difference</li>
212
213        <li><kbd>P</kbd> - move to the previous difference</li>
214
215        <li><kbd>Ctrl-Q</kbd> - exit</li>
216      </ul>
217    </li>
218
219    <li>If you want to use another diff tool instead of <code>xxdiff</code> to
220    examine changes, you can define the <code>graphic-diff</code> setting in a
221    FCM external configuration file (i.e.<samp>$FCM/etc/fcm/external.cfg</samp>
222    or <samp>$HOME/.metomi/fcm/external.cfg</samp>). For example, to use <code>
223      tkdiff</code>, you can do:
224      <pre>
225# in your site's $FCM/etc/fcm/external.cfg:
226# OR: in your $HOME/.metomi/fcm/external.cfg:
227graphic-diff = tkdiff
228</pre>
229    </li>
230  </ul>
231
232  <h4 id="svn_basic_conflicts">Resolving Conflicts</h4>
233
234  <p>Your working copy may contain files or directories <em>in conflict</em> as
235  a result of an update or a merge (covered later). Conflicts arise from the
236  situation where two changes being applied to a file <em>overlap</em>. These
237  can be text-based, as in two changes to the same line of text in a file, or
238  filesystem-based, as in two different renamings of the same file.</p>
239
240  <p>For conflicts in normal (text) files, the command <code>fcm
241  conflicts</code> can be used to help resolve them. (A discussion on binary
242  files is given in the section <a href="working_practices.html#binary">Working
243  with Binary Files</a> later in this document.). For each file in <em>text
244  conflict</em>, the <code>fcm conflicts</code> command calls a graphical merge
245  tool (i.e. <code>xxdiff</code> by default) to display a 3-way diff.</p>
246
247  <p>An example display from <code>xxdiff</code> is shown below.</p>
248
249  <p class="image"><img src="xxdiff2.png" alt="xxdiff 3-way display" /><br />
250  <code>xxdiff</code> 3-way display</p>
251
252  <p>Points to note:</p>
253
254  <ul>
255    <li>The file in the middle is the common ancestor from the merge. The file
256    on the left is your original file and the file on the right is the file
257    containing the changes which you are merging in.</li>
258
259    <li><code>xxdiff</code> is configured to automatically select regions that
260    would end up being selected by an automatic merge (e.g. there are only
261    changes in one of the files). Any difference <em>hunks</em> which cannot be
262    resolved automatically are left <em>unselected</em>.</li>
263
264    <li>Before you can save a merged version you need to go through each
265    unselected difference hunk and decide which text you wish to use.
266
267      <ul>
268        <li>Selecting a diff hunk can be carried out by clicking on it with the
269        left mouse button (or refer to the keyboard shortcuts shown under the
270        <kbd>Region</kbd> menu). The colours update to display which side is
271        selected for output. You can select individual lines with the middle
272        mouse button.</li>
273
274        <li>If you want to select more than one side, you have to invoke the
275        <kbd>Region-&gt;Split/swap/join</kbd> command (keyboard shortcut:
276        <kbd>S</kbd>). This will split the current diff hunk so you can select
277        the pieces you want from both sides. Further invocations of this
278        command will cause swapping of the regions, looping through all the
279        different ordering possibilities, and finally joining the regions again
280        (preserving selections where it is possible).</li>
281      </ul>
282    </li>
283
284    <li>The number on the far right is the number of unselected difference
285    hunks (1 in the example above). Once this number is 0 then you are ready to
286    save the merged file.</li>
287
288    <li>If you want to see how the merged file will look with the current
289    selections then select <kbd>Windows-&gt;Toggle Merged View</kbd> (keyboard
290    shortcut: <kbd>Alt+Y</kbd>). An extra window then appears showing the
291    merged output that updates interactively as you make selections.</li>
292
293    <li>You may find the following keyboard shortcuts useful.
294
295      <ul>
296        <li><kbd>B</kbd> - move to the next unselected hunk</li>
297
298        <li><kbd>O</kbd> - move to the previous unselected hunk</li>
299      </ul>
300    </li>
301
302    <li>There are several different ways to exit the 3-way diff (available from
303    the <kbd>File</kbd> menu):
304
305      <ul>
306        <li>Exit with MERGE (keyboard shortcut: <kbd>M</kbd>) - This saves the
307        merge result. If there are any unselected difference hunks remaining
308        then you will be warned and given the option of saving the file with
309        conflict markers.</li>
310
311        <li>Exit with ACCEPT (keyboard shortcut: <kbd>A</kbd>) - This saves the
312        file you are merging in (i.e. the right one) as the merge result (i.e.
313        you have <em>accepted</em> all the changes).</li>
314
315        <li>Exit with REJECT (keyboard shortcut: <kbd>R</kbd>) - This saves the
316        original working copy file (i.e. the left one) as the merge result
317        (i.e. you have <em>rejected</em> all the changes).</li>
318      </ul>
319
320      <p>If you just want to exit without making any decisions you can also
321      just close the window.</p>
322    </li>
323
324    <li>For further details please read the <a href=
325    "http://furius.ca/xxdiff/doc/xxdiff-doc.html"><code>xxdiff</code> users
326    manual</a> (available from the <kbd>Help</kbd> menu). In particular, read
327    the section <a href=
328    "http://furius.ca/xxdiff/doc/xxdiff-doc.html#merging-files-and-resolving-conflicts">
329    <em>Merging files and resolving conflicts</em></a>.</li>
330  </ul>
331
332  <p>If you have resolved all the conflicts in a file then you will be prompted
333  on whether to run <code>svn resolved</code> on the file to signal that the
334  file is no longer in conflict.</p>
335  <pre>
336(SHELL PROMPT)$ fcm conflicts
337Conflicts in file: Gen_setup_local1.proc
338You have chosen to ACCEPT all the changes
339Would you like to run "svn resolved"?
340Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
341Resolved conflicted state of 'Gen_setup_local1.proc'
342Conflicts in file: Gen_setup_remote2.proc
343Merge conflicts were not all resolved
344Conflicts in file: Gen_setup_remote3.proc
345All merge conflicts resolved
346Would you like to run "svn resolved"?
347Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
348Resolved conflicted state of 'Gen_setup_remote3.proc'
349</pre>
350
351  <p>It is important to realise that there are some types of merge that
352  <code>xxdiff</code> will not be able to help you with.</p>
353
354  <ul>
355    <li>It you have 2 versions of a file, both with substantial changes to the
356    same piece of code, then the <code>xxdiff</code> display will be extremely
357    colourful and not very helpful.</li>
358
359    <li>In these cases it is often easier to start with one version of the file
360    and manually re-apply the changes from the other version. It might not be
361    obvious how to do this and you may need to speak to the author of the other
362    change to agree how this can be done. Fortunately this situation should be
363    very rare.</li>
364
365    <li>For a more detailed discussion please refer to <a href=
366    "http://software.ericsink.com/scm/scm_file_merge.html">Chapter 3: File
367    Merge</a> in the online book called <a href=
368    "http://software.ericsink.com/scm/source_control.html">Source Control
369    HOWTO</a>.</li>
370  </ul>
371
372  <p>For files in <em>tree conflict</em>, which is otherwise known as a
373  structural or filesystem-based conflict, the command <code>fcm
374  conflicts</code> will manually resolve the problem by prompting you to choose
375  a course of action. You can either keep the file as it was before the merge
376  (<em>keep local</em>), or accept the external changes to the file.</p>
377
378  <p>The most common way to generate a tree conflict after a merge is when a
379  file has been deleted or renamed on one branch, and modified on another.
380  These are incompatible changes, to Subversion, and it doesn't know which
381  action to take. This is the cause of the tree conflict dilemma which the user
382  must solve.</p>
383
384  <p>In the following example, the branch in the working copy has had a
385  deletion of a file. The branch that is being merged in has subsequently
386  modified the file, which means that you may want to incorporate these
387  changes. A tree conflict is therefore flagged up.</p>
388  <pre>
389(SHELL PROMPT)$ fcm merge fcm:tutorial_br/dev/bfitz/r1_366
390Merge(s) available from /tutorial/branches/dev/bfitz/r1_366: 1257
391About to merge in changes from /tutorial/branches/dev/bfitz/r1_366@1257 compared with /tutorial/trunk@1
392This merge will result in the following change:
393--------------------------------------------------------------------------------
394--- Merging r2 through r1257 into '.':
395   C src/subroutine/hello_sub.f90
396Summary of conflicts:
397  Tree conflicts: 1
398--------------------------------------------------------------------------------
399Would you like to go ahead with the merge?
400Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
401Performing merge ...
402--- Merging r2 through r1257 into '.':
403   C src/subroutine/hello_sub.f90
404Summary of conflicts:
405  Tree conflicts: 1
406(SHELL PROMPT)$ fcm status
407 M      .
408!     C src/subroutine/hello_sub.f90
409      &gt;   local missing, incoming edit upon merge
410(SHELL PROMPT)$ fcm info src/subroutine/hello_sub.f90
411Path: src/subroutine/hello_sub.f90
412Name: hello_sub.f90
413Node Kind: none
414Tree conflict: local missing, incoming edit upon merge
415  Source  left: (file) svn://fcm1/tutorial_svn/tutorial/trunk/src/subroutine/hello_sub.f90@1
416  Source right: (file) svn://fcm1/tutorial_svn/tutorial/branches/dev/bfitz/r1_366/src/subroutine/hello_sub.f90@1257
417</pre>
418
419  <p>In this example, running <code>fcm conflicts</code> would give:</p>
420  <pre>
421(SHELL PROMPT)$ fcm conflicts
422[info] src/subroutine/hello_sub.f90: in tree conflict.
423Locally: deleted
424Externally: modified.
425Answer (y) to leave the file deleted.
426Answer (n) to add the file with the changes.
427Keep the local version?
428Enter "y" or "n" (or just press &lt;return&gt; for "n")
429</pre>
430
431  <p>In this example, to keep the file as it was before (in a deleted state),
432  enter <samp>y</samp>.</p>
433
434  <p>Otherwise, to accept the merge branch version of the file (adding it with
435  the edited changes), enter <samp>n</samp>.</p>
436
437  <p>There are many other types of tree conflicts that can occur, and <code>fcm
438  conflicts</code> does not cover all of them. Tree conflicts arising from
439  updates and switches are not covered (which should be rare under FCM working
440  practice). More importantly, tree conflicts on directories are not covered,
441  because of the potential nesting of conflicts within the directories. It can
442  often be difficult to identify the problem and figure out the solution in the
443  case of directory conflicts, and the easiest solution may be to try to
444  resolve the discrepancy before the merge.</p>
445
446  <p>For further details, see the <a href=
447  "annex_quick_ref_tree_conflicts.html">Tree Conflict</a> annex</p>
448
449  <h4 id="svn_basic_check">Adding and Removing Files</h4>
450
451  <p>If your working copy contains files which are not under version control
452  then you can use the command <code>fcm add --check</code> to add them. This
453  will go through each of the files and prompt to see if you wish to put that
454  file under version control using <code>svn add</code>. For each file you can
455  enter <kbd>y</kbd> for yes, <kbd>n</kbd> for no or <kbd>a</kbd> to assume yes
456  for all following files.</p>
457  <pre>
458(SHELL PROMPT)$ fcm add -c
459?      xxdiff1.png
460?      xxdiff2.png
461?      xxdiff3.png
462?      xxdiff4.png
463Add file 'xxdiff1.png'?
464Enter "y", "n" or "a" (or just press &lt;return&gt; for "n"): y
465A         xxdiff1.png
466Add file 'xxdiff2.png'?
467Enter "y", "n" or "a" (or just press &lt;return&gt; for "n"): n
468Add file 'xxdiff3.png'?
469Enter "y", "n" or "a" (or just press &lt;return&gt; for "n"): a
470A         xxdiff3.png
471A         xxdiff4.png
472</pre>
473
474  <p>Similarly, if your working copy contains files which are missing (i.e. you
475  have deleted them without using <code>svn delete</code>) then you can use the
476  command <code>fcm delete --check</code> to delete them. This will go through
477  each of the files and prompt to see if you wish to remove that file from
478  version control using <code>svn delete</code>.</p>
479
480  <p>As noted in the <a href=
481  "http://subversion.apache.org/faq.html#wc-change-detection">Subversion
482  FAQ</a>, it can be dangerous using these commands. If you have moved or
483  copied a file then simply adding them would cause the history to be lost.
484  Therefore take care to only use these commands on files which really are new
485  or deleted.</p>
486
487  <h4 id="svn_basic_commit">Committing Changes</h4>
488
489  <p>The command <code>fcm commit</code> should be used for committing changes
490  back to the repository. It differs from the <code>svn commit</code> command
491  in a number of important ways:</p>
492
493  <ul>
494    <li>Your working copy <em>must</em> be up to date. <code>fcm commit</code>
495    will abort if it finds that any files are out of date with respect to the
496    repository. This ensures that your working copy reflects how the repository
497    will be after you have committed your changes.
498
499      <ul>
500        <li>This helps to ensure that any tests you have done prior to
501        committing are valid.</li>
502
503        <li><code>fcm commit</code> is not suitable if you need to commit
504        changes from a working copy containing mixed revisions. However, you
505        are very unlikely to need to do this.</li>
506
507        <li>Actually there is a small chance that your working copy might not
508        be up to date when you commit if someone else is committing some
509        changes at the same time. However, this should very seldom happen and,
510        even if it does, the commit would fail if any of the files being
511        changed became out of date (i.e. it is not possible to lose any
512        changes).</li>
513      </ul>
514    </li>
515
516    <li>If it discovers a file named <samp>#commit_message#</samp> in the top
517    level of your working copy it uses this to provide a template commit
518    message (which you can then edit).
519
520      <ul>
521        <li>If you have performed a merge then a message describing the merge
522        will have been added to this file. It is important that you leave this
523        included in the commit message and do not change its format, as it is
524        used by the <code>fcm branch-info</code> command.</li>
525
526        <li>You can, if you wish, add entries to this file as you go along to
527        record what changes you have prepared in your working copy. You can
528        also use the command <code>fcm commit --dry-run</code> to allow you to
529        edit the commit message without committing any changes.</li>
530
531        <li><samp>#commit_message#</samp> is ignored by Subversion (so you
532        won't see it show up as an unversioned files when you run <code>fcm
533        status</code>).</li>
534      </ul>
535    </li>
536
537    <li>It always operates from the top of your working copy. If you issue the
538    <code>fcm commit</code> command from a sub-directory of your working copy
539    then it will automatically work out the top directory and work from there.
540
541      <ul>
542        <li>This ensures that any template commit message gets picked up and
543        that you do not, for example, accidently commit a partial set of
544        changes from a merge.</li>
545      </ul>
546    </li>
547
548    <li>It always commits <em>all</em> the changes in your working copy (it
549    does not accept a list of files to commit).
550
551      <ul>
552        <li>Once again, this avoids any danger of accidently committing a
553        partial set of changes.</li>
554
555        <li>You should only work on one change within a working copy. If you
556        need to prepare another, unrelated change then use a separate working
557        copy.</li>
558      </ul>
559    </li>
560
561    <li>It runs <code>svn update</code> after the commit to ensure that your
562    working copy is at the latest revision and to avoid any confusion caused by
563    your working copy containing mixed revisions.</li>
564  </ul>
565  <pre>
566(SHELL PROMPT)$ fcm commit
567Starting editor to create commit message ...
568Change summary:
569------------------------------------------------------------------------
570[Project: GEN]
571[Branch : branches/test/frsn/r123_foo_bar]
572[Sub-dir: &lt;top&gt;]
573
574M      src/code/GenMod_Control/GenMod_Control.f90
575M      src/code/GenMod_Control/Gen_SetupControl.f90
576------------------------------------------------------------------------
577Commit message is as follows:
578------------------------------------------------------------------------
579An example commit.
580------------------------------------------------------------------------
581Would you like to commit this change?
582Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
583Sending        src/code/GenMod_Control/GenMod_Control.f90
584Sending        src/code/GenMod_Control/Gen_SetupControl.f90
585Transmitting file data ..
586Committed revision 170.
587=&gt; svn update
588At revision 170.
589</pre>
590
591  <h3 id="svn_branching">Branching And Merging</h3>
592
593  <p>Branching is a fundamental concept common to most version control systems.
594  For a good introduction please read the chapter <a href=
595  "http://svnbook.red-bean.com/en/1.8/svn.branchmerge.html">Branching and
596  Merging</a> from the <cite>Subversion book</cite>. Even if you are already
597  familiar with branching using other version control systems you should still
598  read this chapter to see how branching is implemented in Subversion.</p>
599
600  <p>Having read this chapter from the <cite>Subversion book</cite> you should
601  understand:</p>
602
603  <ul>
604    <li>Why each project directory has sub-directories called <em>trunk</em>,
605    <em>branches</em> and <em>tags</em>. This structure is assumed by
606    <code>fcm</code> (Subversion recommends it but doesn't insist on it).</li>
607
608    <li>That when you make a branch you are taking a copy of the entire project
609    file tree. Fortunately, the design of the Subversion repository means that
610    these copies are <q title=
611    "http://svnbook.red-bean.com/en/1.8/svn.branchmerge.using.html#svn.branchmerge.using.create">
612    cheap</q> - they are quick to create and take very little space.</li>
613
614    <li>That Subversion has only implemented merge tracking recently,
615    long after FCM has implemented its own solution optimised for our
616    recommended working practice.</li>
617
618    <li>That each revision of your repository can also be thought of as a
619    <em>changeset</em>.</li>
620
621    <li>That once a change is committed to a repository it cannot be removed
622    (only reversed). Therefore you must take care not to committ a sensitive
623    document or a large data file unintentionally.</li>
624  </ul>
625
626  <p>FCM provides various commands which make working with branches easier (as
627  described in the following sections).</p>
628
629  <h4 id="svn_branching_create">Creating Branches</h4>
630
631  <p>The command <code>fcm branch-create</code> (or simply <code>fcm
632  bcreate</code> or even <code>fcm bc</code>) should be used for creating new
633  branches. It provides a number of features:</p>
634
635  <ul>
636    <li>It applies a standard naming convention for branches. The branch name
637    is automatically constructed for you depending on the option(s) supplied to
638    the command. The full detail of these options are described in the <a href=
639    "command_ref.html#fcm-branch-create">FCM Command Reference &gt; fcm
640    branch-create</a> section.</li>
641
642    <li>By default, it assumes that you are branching from the last changed
643    revision of the <em>trunk</em>.
644
645      <ul>
646        <li>You can use the <code>--branch-of-branch</code> option if you need
647        to create a branch of a branch. A branch of a branch can be useful in
648        many situations. For example, consider a shared branch used by several
649        members of your team to develop, say, a new science scheme, and you
650        have come up with some different ideas of implementing the scheme. You
651        may want to create a branch of the shared branch to develop your idea
652        before merging it back to the shared branch. Note that you can only
653        merge a branch of a branch with it's parent or with another branch
654        created from the same parent. You can't, for example, merge it with the
655        trunk.</li>
656
657        <li>You can do <code>fcm bc NAME SOURCE@REV</code> if you
658        need to create a branch from an earlier revision of the SOURCE.</li>
659      </ul>
660    </li>
661
662    <li>Each branch always contains a full copy of the trunk (or its parent
663    branch) - you cannot create a branch from a sub-tree.
664
665      <ul>
666        <li>There would be no reason to only include a sub-tree in a
667        branch.</li>
668      </ul>
669    </li>
670
671    <li>It applies a standard commit message which defines how the branch has
672    been created. If a Trac ticket is specified using the <code>--ticket
673    &lt;number&gt;</code> option, it is added to the commit log message. If you
674    need to add anything to the commit log message, please do so
675    <strong>above</strong> the line that says <samp>--Add your commit message
676    ABOVE - do not alter this line or those below--</samp>.</li>
677  </ul>
678
679  <p>The following is a list of the different types of branches available:</p>
680
681  <dl>
682    <dt>User development branches</dt>
683
684    <dd><samp>branches/dev/&lt;Userid&gt;/&lt;Branch_Name&gt;</samp> These are
685    for changes which are intended to be merged back to the trunk once they are
686    complete. Most branches will belong to this type. e.g.
687    branches/dev/frdm/vn6.1_ImprovedDeepConvection,
688    branches/dev/frdm/r2134_NewBranchNamingConvention.</dd>
689
690    <dt>Shared development branches</dt>
691
692    <dd><samp>branches/dev/Share/&lt;Branch_Name&gt;</samp></dd>
693
694    <dt>User test branches</dt>
695
696    <dd><samp>branches/test/&lt;Userid&gt;/&lt;Branch_Name&gt;</samp> These are
697    for changes which are <em>not</em> intended for the trunk. e.g. Proof of
698    concept work, temporary code written for dealing with a one-off problem,
699    etc.</dd>
700
701    <dt>Shared test branches</dt>
702
703    <dd><samp>branches/test/Share/&lt;Branch_Name&gt;</samp></dd>
704
705    <dt>User packages</dt>
706
707    <dd><samp>branches/pkg/&lt;Userid&gt;/&lt;Branch_Name&gt;</samp> These are
708    branches which combine together a number of different development branches.
709    Sometimes this will simply be for testing purposes (i.e. for testing a
710    branch in combination with other branches). Other times it may be the
711    package which eventually gets merged to the trunk (rather than the
712    development branches). e.g.
713    branches/pkg/frdm/vn6.1_TestImprovedDeepConvection</dd>
714
715    <dt>Shared packages</dt>
716
717    <dd><samp>branches/pkg/Share/&lt;Branch_Name&gt;</samp> E.g.
718    branches/pkg/Share/vn6.1_NewConvectionScheme.</dd>
719
720    <dt>Configurations</dt>
721
722    <dd><samp>branches/pkg/Config/&lt;Branch_Name&gt;</samp> These are major
723    packages which combine together a number of different packages and
724    development branches. e.g. branches/pkg/Config/vn6.1_HadGEM1a.</dd>
725
726    <dt>Releases</dt>
727
728    <dd><samp>branches/pkg/Rel/&lt;Branch_Name&gt;</samp> These may be bug-fix
729    branches for system releases, if required. They can also be branches on
730    which stable releases are prepared if you don't do this on the trunk
731    (although you lose the ability to branch from stable releases if you work
732    this way). e.g. branches/pkg/Rel/vn6.1_BugFixes.</dd>
733  </dl>
734  <pre>
735(SHELL PROMPT)$ fcm bcreate -k 23 my_test_branch fcm:test
736Starting nedit to create commit message ...
737Change summary:
738------------------------------------------------------------------------
739A    svn://fcm1/repos/OPS/branches/dev/frsn/r118_my_test_branch
740------------------------------------------------------------------------
741Commit message is as follows:
742------------------------------------------------------------------------
743Create an example branch to demonstrate branch creation for the user guide.
744#23: Created /OPS/branches/dev/frsn/r118_my_test_branch from /OPS/trunk@118.
745------------------------------------------------------------------------
746Would you like to go ahead and create this branch?
747Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
748Creating branch svn://fcm1/repos/OPS/branches/dev/frsn/r118_my_test_branch ...
749
750Committed revision 169.
751</pre>
752
753  <h4 id="svn_branching_list">Listing Branches Created by You or Other
754  Users</h4>
755
756  <p>The command <code>fcm branch-list</code> (or simply <code>fcm bls</code>)
757  can be used to list the branches you have created at the HEAD of a
758  repository. If you specify the <code>--user &lt;userid&gt;</code> option, the
759  branches created by &lt;userid&gt; are listed instead. You can specify
760  multiple users with multiple <code>--user &lt;userid&gt;</code> options, or
761  with a colon (:) separated list to a single <code>--user
762  &lt;userid:list&gt;</code> option. Note that you can also list shared
763  branches by specifying &lt;userid&gt; as <code>Share</code>, configuration
764  branches by specifying &lt;userid&gt; as <code>Config</code> and release
765  branches by specifying &lt;userid&gt; as <code>Rel</code>. The command
766  returns 0 (success) if one or more branches is found for the specified users,
767  or 1 (failure) if no branch is found.</p>
768  <pre>
769(SHELL PROMPT)$ fcm branch-list fcm:gen
7701 branch found for frsn in svn://fcm1/GEN_svn/GEN
771fcm:GEN-br/dev/frsn/r1191_clean_up/
772(SHELL PROMPT)$ echo $?
7730
774(SHELL PROMPT)$ fcm branch-list --user frbj --user frsn fcm:gen
7752 branches found for frbj, frsn in svn://fcm1/GEN_svn/GEN
776fcm:GEN-br/dev/frbj/r1177_gen_ui_for_scs/
777fcm:GEN-br/dev/frsn/r1191_clean_up/
778(SHELL PROMPT)$ echo $?
7790
780(SHELL PROMPT)$ fcm branch-list --user frva fcm:gen
7810 branch found for frva in svn://fcm1/GEN_svn/GEN
782(SHELL PROMPT)$ echo $?
7831
784</pre>
785
786  <h4 id="svn_branching_info">Getting Information About Branches</h4>
787
788  <p>The command <code>fcm branch-info</code> (or simply <code>fcm
789  binfo</code>) can be used to get various information about a branch. In
790  particular, it summarises information about merges to and from the branch and
791  its parent.</p>
792  <pre>
793(SHELL PROMPT)$ fcm branch-info
794URL: svn://fcm1/FCM_svn/FCM/branches/dev/frsn/r1346_merge
795Repository Root: svn://fcm1/FCM_svn
796Revision: 1385
797Last Changed Author: frsn
798Last Changed Rev: 1385
799Last Changed Date: 2006-04-20 11:08:45 +0100 (Thu, 20 Apr 2006)
800--------------------------------------------------------------------------------
801Branch Create Author: frsn
802Branch Create Rev: 1354
803Branch Create Date: 2006-04-04 14:27:47 +0100 (Tue, 04 Apr 2006)
804Branch Parent: svn://fcm1/FCM_svn/FCM/trunk@1346
805Last Merge From Parent, Revision: 1444
806Last Merge From Parent, Delta: /FCM/trunk@1439 cf. /FCM/trunk@1395
807Merges Avail From Parent: 1445
808Merges Avail Into Parent: 1453 1452 1449 1446 1444 1443 1441 1434 1397 1396 ...
809</pre>
810
811  <p>If you need information on the current children of the branch, use the
812  <code>--show-children</code> option of the <code>fcm branch-info</code>
813  command. If you need information on recent merges to and from the branch and
814  its siblings, use the <code>--show-siblings</code> option of the <code>fcm
815  branch-info</code> command.</p>
816
817  <p>To find out what changes have been made on a branch relative to its parent
818  you can use the command <code>fcm branch-diff</code> (or simply <code>fcm
819  bdi</code>.</p>
820
821  <ul>
822    <li>You can combine this with the options:
823
824      <dl>
825        <dt><code>--graphical</code></dt>
826
827        <dd>to display the differences using a graphical <em>diff</em>
828        tool</dd>
829
830        <dt><code>--trac</code></dt>
831
832        <dd>to display the differences using Trac</dd>
833
834        <dt><code>--wiki</code></dt>
835
836        <dd>to print a wiki syntax suitable for inserting into Trac</dd>
837      </dl>
838    </li>
839
840    <li>The base of the difference is adjusted to account for any merges from
841    the branch to its parent or vice-versa.</li>
842  </ul>
843
844  <h4 id="svn_branching_switch">Switching your working copy to point to another
845  branch</h4>
846
847  <p>The command <code>fcm switch</code> can be used to switch your working
848  copy to point to another branch. For example, if you have a working copy at
849  <samp>$HOME/work</samp>, currently pointing to the trunk or a branch of a
850  project at <samp>svn://fcm1/FCM_svn/FCM/trunk</samp>, you can switch the
851  working copy to point to another branch of same project:</p>
852  <pre>
853(Shell prompt)$ cd $HOME/work
854(Shell prompt)$ fcm sw dev/frsn/r959_blockdata
855-&gt; svn switch --revision HEAD svn://fcm1/FCM_svn/FCM/branches/dev/frsn/r959_blockdata
856U    doc/user_guide/getting_started.html
857U    doc/user_guide/code_management.html
858U    doc/user_guide/command_ref.html
859U    src/lib/FCM1/SrcFile.pm
860U    src/lib/FCM1/Util.pm
861U    src/lib/FCM1/Build.pm
862U    src/lib/FCM1/Cm.pm
863U    src/lib/FCM1/SrcPackage.pm
864U    src/bin/fcm_internal
865U    src/bin/fcm_gui
866Updated to revision 1009.
867</pre>
868
869  <p>Unlike <code>svn switch</code>, <code>fcm switch</code> does extra
870  checking to ensure that your whole working copy is switched to the new branch
871  at the correct level of sub-directory. In addition, you can specify only the
872  <em>branch</em> part of the URL, such as <samp>trunk</samp>,
873  <samp>branches/dev/fred/r1234_bob</samp> or even
874  <samp>dev/fred/r1234_bob</samp> and the command will work out the full URL
875  for you.</p>
876
877  <h4 id="svn_branching_delete">Deleting Branches</h4>
878
879  <p>The command <code>fcm branch-delete</code> (or simply <code>fcm
880  bdel</code>) can be used to delete branches which are no longer required.
881  Before being asked to confirm that you want to delete the branch, you will
882  first see the same output as from <code>fcm branch-info</code>. This allows
883  you to check, for example, whether your branch is being used anywhere else or
884  whether the latest changes on your branch have been merged to the trunk. You
885  will be prompted to edit your commit log message. If you need to add anything
886  to the commit log message, please do so <strong>above</strong> the line that
887  says <samp>--Add your commit message ABOVE - do not alter this line or those
888  below--</samp>.</p>
889
890  <h4 id="svn_branching_merge">Merging</h4>
891
892  <p>As mentioned earlier, <code>fcm</code> has its own merge tracking solution
893  which is optimised for our recommended working practice. The solution assumes
894  the following:</p>
895
896  <ul>
897    <li>That all merges are performed using FCM and are identified using a
898    standard template in the commit log message.</li>
899
900    <li>That you only ever merge all the changes available on the source branch
901    up to a chosen point (i.e. you can't only include a subset of the changes
902    made to the branch).</li>
903
904    <li>That the source and target are both branches (or the trunk) in the same
905    FCM project.</li>
906
907    <li>That the source and target are directly related, i.e. they must either
908    have a parent/child relationship or they are siblings from the same parent
909    branch.</li>
910  </ul>
911
912  <p>Note that the term <em>source branch</em> and <em>target branch</em>
913  referred to above can also mean the trunk.</p>
914
915  <p>To perform a merge, use the command <code>fcm merge &lt;source&gt;</code>.
916  This includes a number of important features:</p>
917
918  <ul>
919    <li>If it finds any local modifications in your working copy then it checks
920    whether you wish to continue (in most cases you won't want to mix a merge
921    with other changes).</li>
922
923    <li>It determines the base revision and path of the <em>common
924    ancestor</em> to be used for the merge, taking into account any merges from
925    the <em>source</em> to the <em>target</em> or vice-versa.</li>
926
927    <li>Before doing the merge, (unless you specify the
928    <code>--non-interactive</code> option), it reports what changes will result
929    from performing the merge and checks that you wish to continue.</li>
930
931    <li>It adds details of the merge, using a standard template, into the
932    commit message file (<samp>#commit_message#</samp>). If you need to add any
933    extra comment, you should do so <strong>above</strong> the line that says
934    <samp>--Add your commit message ABOVE - do not alter this line or those
935    below--</samp>.
936
937      <ul>
938        <li>If you decide to revert the merge, you should remove the template
939        line manually from the commit message file, making sure that you do not
940        alter the standard template by accident.</li>
941
942        <li>If the <code>--auto-log</code> option is specified, it adds the log
943        messages of the merged revisions as well as the standard template. This
944        is particularly useful when a small change is prepared in a branch, and
945        often the same commit log messages have to be repeated when the change is
946        merged and committed to the trunk. The option does not work very well if
947        the branch contains merges from another branch.</li>
948      </ul>
949    </li>
950  </ul>
951  <pre>
952(SHELL PROMPT)$ fcm merge trunk # merge changes from the trunk into the branch
953Eligible merge(s) from FCM/trunk: 1383 1375
954Enter a revision (or just press &lt;return&gt; for "1383"):
955Merge: /FCM/trunk@1383
956 c.f.: /FCM/trunk@1371
957-------------------------------------------------------------------------dry-run
958A    doc/fortran_standards/index.html
959U    src/lib/FCM1/ReposBranch.pm
960-------------------------------------------------------------------------dry-run
961Would you like to go ahead with the merge?
962Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
963Merge succeeded.
964</pre>
965
966  <h3 id="svn_gui">Using the GUI</h3>
967
968  <p>So far, all the tools described have been command line tools. Many people
969  will be happy with these but, for those who prefer it, there is also a simple
970  Graphical User Interface (GUI).</p>
971
972  <h4 id="svn_gui_start">Starting the GUI</h4>
973
974  <p>To run the GUI simply issue the command <code>fcm gui</code> from the
975  directory you want as your working directory.</p>
976
977  <p>The GUI consists of several sections:</p>
978
979  <ul>
980    <li>The top section contains a row of buttons to allow you to select which
981    command you want to run.</li>
982
983    <li>Beneath this is shown the current working directory and the top level
984    directory of your working copy (these may be the same).</li>
985
986    <li>Beneath this come various buttons and entry boxes to allow you to
987    configure the command you have selected. These vary according to the
988    command.</li>
989
990    <li>Beneath this comes a further row of buttons
991
992      <ul>
993        <li><em>Quit</em> - this exits the GUI.</li>
994
995        <li><em>Help</em> - this displays the help message for the selected
996        command.</li>
997
998        <li><em>Clear</em> - this empties the text window.</li>
999
1000        <li><em>Run</em> - this allows you to run your command.</li>
1001      </ul>
1002    </li>
1003
1004    <li>Beneath this comes a scrolling text window where the output from the
1005    commands is displayed.</li>
1006
1007    <li>The bottom section displays help information when you position the
1008    cursor over various parts of the GUI.</li>
1009  </ul>
1010
1011  <p class="image"><img src="gui1.png" alt=
1012  "Example GUI screen with the Status commands selected" /><br />
1013  Example GUI screen with the <kbd>Status</kbd> commands selected</p>
1014
1015  <p>If you run a more complicated command, like <code>fcm
1016  branch-create</code>, which prompts for input then extra entry windows will
1017  pop up.</p>
1018
1019  <p class="image"><img src="gui2.png" alt="Example GUI pop-up window" /><br />
1020  Example GUI pop-up window</p>
1021
1022  <h4 id="svn_gui_commands">GUI Commands</h4>
1023
1024  <p>The commands available from the GUI should be self explanatory. A few
1025  points to note:</p>
1026
1027  <ul>
1028    <li>If the current directory is not a working copy, you will only be able
1029    to Checkout a working copy or create a branch from the GUI.</li>
1030
1031    <li>The <kbd>Checkout</kbd> command is only available if you start the GUI
1032    in a directory which is not already a working copy. After successfully
1033    running a checkout the GUI automatically sets the working directory to the
1034    top of this new working copy.</li>
1035
1036    <li>With some commands (Status, Diff, Add, Delete, Conflicts) you can
1037    choose whether to run from the top level of your working copy or from your
1038    working directory. With the remaining commands this would not make sense
1039    and they can only be run from the top level.</li>
1040
1041    <li>You can only issue commands from the GUI if they do not need to prompt
1042    you for authentication (i.e. the Subversion command can be run with the
1043    <code>--non-interactive</code> option).
1044
1045      <ul>
1046        <li>If authentication is required then the command issued by the GUI
1047        will fail. For the <code>branch-create</code>,
1048        <code>branch-delete</code> and <code>commit</code> commands, which
1049        support the <code>--password</code> option, you should specify your
1050        password in <kbd>Other options</kbd> and click <kbd>Run</kbd> again.
1051        For other commands, you should run the command in interactive mode on
1052        the command line. Use the command displayed in the GUI text window but
1053        remove the <code>--non-interactive</code> option.</li>
1054
1055        <li>Most repositories will be configured so that you only need
1056        authentication for writing (not reading). Therefore, the first command
1057        requiring authentication will probably be creating a branch or
1058        commiting to the trunk.</li>
1059
1060        <li>You should only need to do this the first time you ever issue such
1061        a command on a each repository (unless the repository is moved to a new
1062        location) since the Subversion client caches this information for
1063        future comamnds .</li>
1064      </ul>
1065    </li>
1066  </ul>
1067
1068  <h3 id="svn_problems">Known Problems with Subversion</h3>
1069
1070  <p>There is a limitation with Subversion which you should be aware of. The
1071  <code>svn rename</code> command is not a true rename/move operation, but is
1072  implemented as a copy and delete. As a result, if you rename an item in a
1073  branch, and later attempt to merge it back to the trunk, the operation may
1074  not be handled correctly by <code>svn merge</code> (see <a href=
1075  "http://subversion.tigris.org/issues/show_bug.cgi?id=898">subversion issue
1076  898</a> for further details). Until such time as support for a <q title=
1077  "http://subversion.tigris.org/issues/show_bug.cgi?id=898">true rename</q> is
1078  implemented in Subversion, you should avoid renaming of files or directories
1079  unless you can ensure that no-one is working in parallel on the affected
1080  areas of the project.</p>
1081
1082  <h2 id="trac">Using Trac</h2>
1083
1084  <p><cite>Trac</cite> has a simple and intuitive web interface which is
1085  relatively easy to pick up. It also includes a <a href=
1086  "http://trac.edgewall.org/wiki/TracGuide">User and Administration Guide</a>
1087  which is full of helpful information (and is referred to extensively in this
1088  section).</p>
1089
1090  <p>Trac contains a menu bar at the top of each page (which we will refer to
1091  as the <cite>Trac menu</cite>). This provides access to all the main
1092  features.</p>
1093
1094  <h3 id="trac_login">Logging In</h3>
1095
1096  <p>Although different projects may choose their own rules, we expect that
1097  most systems will have Trac configured so that all the information is
1098  viewable by anyone. However, in order to make any changes you will need to
1099  login. This ensures that any changes are identified with the appropriate
1100  userid.</p>
1101
1102  <p>In the rest of this section it is assumed that you have logged in to Trac
1103  and are therefore able to make changes.</p>
1104
1105  <p>If you haven't yet got a Trac userid (which should be the same as the
1106  userid you use for committing changes to Subversion) then please contact your
1107  system manager.</p>
1108
1109  <h3 id="trac_wiki">Using the Wiki Pages</h3>
1110
1111  <p>A wiki enables documents to be written in a simple markup language using a
1112  web browser. See the Trac Guide for information on the <a href=
1113  "http://trac.edgewall.org/wiki/TracWiki">Trac Wiki Engine</a>. Make sure that
1114  you read the information provided on:</p>
1115
1116  <ul>
1117    <li><a href="http://trac.edgewall.org/wiki/WikiFormatting">Wiki
1118    Formatting</a> which explains how to format your wiki pages.</li>
1119
1120    <li><a href="http://trac.edgewall.org/wiki/WikiPageNames">Wiki Page
1121    Names</a> which explains how <em>CamelCase</em> is used to create <a href=
1122    "http://trac.edgewall.org/wiki/WikiNewPage">New Wiki Pages</a>.</li>
1123
1124    <li><a href="http://trac.edgewall.org/wiki/TracLinks">Trac Links</a> which
1125    allow hyperlinking between Trac entities (tickets, reports, changesets,
1126    Wiki pages, milestones and source files). This is a fundamental feature of
1127    Trac which makes it easy, for example, to link a bug report (ticket) to the
1128    changeset which fixed the bug (and vice-versa).</li>
1129  </ul>
1130
1131  <p>Whenever you are viewing a wiki page in Trac you should see several
1132  buttons at the bottom of the page:</p>
1133
1134  <ul>
1135    <li><kbd>Edit This Page</kbd> - Clicking this will bring up a page where
1136    you can edit the page contents. Before saving your changes you can preview
1137    how the modified page will appear. You can also leave a comment explaining
1138    what changes you made.</li>
1139
1140    <li><kbd>Attach File</kbd> - Allows you to attach files to a page, e.g. an
1141    image.</li>
1142
1143    <li>If you have admin rights then you will also see
1144
1145      <ul>
1146        <li><kbd>Delete This Version</kbd> - Delete the particular version of
1147        the page you are viewing.</li>
1148
1149        <li><kbd>Delete Page</kbd> - Delete the page and all its history.</li>
1150      </ul>Use with care - these operations are irreversible!
1151    </li>
1152  </ul>
1153
1154  <p>At the top of each wiki page at the right hand side you can select
1155  <kbd>Page History</kbd>. This shows you the full history of each page with
1156  details of when each change was made, who made the change and what the
1157  changes were.</p>
1158
1159  <h3 id="trac_browser">Using the Repository Browser</h3>
1160
1161  <p>The <a href="http://trac.edgewall.org/wiki/TracBrowser">Trac Browser</a>
1162  is used to view the contents of your repository. To get to it just select
1163  <kbd>Browse Source</kbd> from the Trac menu. You can view directories and
1164  files at any version, see their revision histories and view <a href=
1165  "http://trac.edgewall.org/wiki/TracChangeset">changesets</a>. Any wiki
1166  formatting in log messages is recognised and interpreted so you can easily
1167  link a changeset to a Trac ticket by using <a href=
1168  "http://trac.edgewall.org/wiki/TracLinks">Trac Links</a>.</p>
1169
1170  <h3 id="trac_tickets">Using the Issue Tracker</h3>
1171
1172  <p>The Trac issue database provides a way of tracking issues within a project
1173  (e.g. bug reports, feature requests, software support issues, project tasks).
1174  Within Trac an issue is often referred to as a <em>Ticket</em>.</p>
1175
1176  <p>Please refer to the Trac Guide for the following information:</p>
1177
1178  <ul>
1179    <li>
1180      <a href="http://trac.edgewall.org/wiki/TracTickets">The Trac Ticket
1181      System</a> - Creating and modifying tickets.
1182
1183      <ul>
1184        <li>Only Trac accounts with admin rights can modify ticket
1185        descriptions.</li>
1186      </ul>
1187    </li>
1188
1189    <li><a href="http://trac.edgewall.org/wiki/TracQuery">Trac Ticket
1190    Queries</a> - List tickets matching your chosen criterion.</li>
1191  </ul>
1192
1193  <h3 id="trac_roadmap">Using the Roadmap</h3>
1194
1195  <p>Each ticket can be assigned to a milestone. The Trac Roadmap can then be
1196  used to provide a view on the ticket system. This can useful to see what
1197  changes went into a particular system release or what changes are outstanding
1198  before a milestone can be reached.</p>
1199
1200  <p>Please refer to the Trac Guide for further information on the <a href=
1201  "http://trac.edgewall.org/wiki/TracRoadmap">Trac Roadmap</a>.</p>
1202
1203  <ul>
1204    <li>Only Trac accounts with admin rights can add, modify and remove
1205    milestones using the web interface.</li>
1206  </ul>
1207
1208  <h3 id="trac_timeline">Using the Timeline</h3>
1209
1210  <p>The <a href="http://trac.edgewall.org/wiki/TracTimeline">Trac Timeline</a>
1211  allows you to list all the activity on a project over any given period. It
1212  can list:</p>
1213
1214  <ul>
1215    <li>Creation and changes to wiki pages.</li>
1216
1217    <li>Creation, closure and changes to tickets.</li>
1218
1219    <li>Commits to the Subversion repository.</li>
1220
1221    <li>Milestones reached.</li>
1222  </ul>
1223
1224  </div>
1225  </div>
1226  </div>
1227
1228  <hr/>
1229  <div class="container-fluid text-center">
1230    <div class="row"><div class="col-md-12">
1231    <address><small>
1232      &copy; British Crown Copyright 2006-16
1233      <a href="http://www.metoffice.gov.uk">Met Office</a>.
1234      See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
1235      This document is released under the British <a href=
1236      "http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
1237      "license">Open Government Licence</a>.<br />
1238    </small></address>
1239    </div></div>
1240  </div>
1241
1242  <script type="text/javascript" src="../etc/jquery.min.js"></script>
1243  <script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
1244  <script type="text/javascript" src="../etc/fcm.js"></script>
1245  <script type="text/javascript" src="../etc/fcm-version.js"></script>
1246</body>
1247</html>
Note: See TracBrowser for help on using the repository browser.