source: OFFICIAL/FCM_V1.3/doc/user_guide/code_management.html

Last change on this file was 1, checked in by fcm, 15 years ago

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