source: LMDZ5/trunk/tools/fcm/doc/user_guide/code_management.html @ 1934

Last change on this file since 1934 was 1578, checked in by jghattas, 13 years ago
  • Add fcm in LMDZ5/tools directory

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