source: codes/icosagcm/trunk/tools/FCM/doc/user_guide/code_management.html @ 10

Last change on this file since 10 was 10, checked in by ymipsl, 12 years ago

dynamico tree creation

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