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

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

dynamico tree creation

YM
File size: 61.5 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5  <title>FCM System User Guide: Getting Started</title>
6  <meta name="author" content="FCM development team">
7  <meta name="descriptions" content="User Guide - Getting Started">
8  <meta name="keywords" content="FCM, user guide, getting started, tutorial">
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; Getting Started
16  </address>
17
18  <h1>Getting Started</h1>
19
20  <p><em>Getting Started</em> is a "hands-on" approach to help you set up your
21  FCM session, and familiarise yourself with some of the system's basic
22  concepts and working practices. It is designed to complement other sections
23  of the User Guide.</p>
24
25  <p>You may also find it useful to refer to the <a href=
26  "annex_quick_ref.html">Annex: Quick reference</a>.</p>
27
28  <h2><a name="setup">How to set yourself up to run FCM</a></h2>
29
30  <p>It is easy to set yourself up to run FCM. Simply follow the steps
31  below:</p>
32
33  <p><strong>Setting up your PATH</strong></p>
34
35  <p>The full FCM system is already available for you to use on the Met Office
36  Linux desktop systems. On other Met Office systems (currently NEC &amp;
37  HP-UX) only the build component is functional.</p>
38
39  <p>On Linux &amp; HP-UX systems FCM is automatically available in the
40  standard PATH. It is also automatically added to your PATH when you run UI
41  jobs on the NEC computers. However, if you intend to run FCM from the command
42  line on the NEC then you will need to add the following to your
43  <tt>$HOME/.profile</tt> script on that platform:</p>
44  <pre>
45. ~fcm/FCM/bin/env.sh  # Add FCM environment
46</pre>
47
48  <p><strong>Setting up the FCM GUI to work with Konqueror</strong></p>
49
50  <p>If you like to use a graphical user interface for some common code
51  management commands, you can set it up for launching from your desktop
52  Konqueror file manager by typing:</p>
53  <pre>
54(SHELL PROMPT)$ fcm_setup_konqueror
55</pre>
56
57  <p>See the section on <a href=
58  "code_management.html#svn_gui_konqueror">Accessing the GUI from Konqueror</a>
59  for further information.</p>
60
61  <p>Note that the first time you issue a command which requires authentication
62  you may need to supply a password or run it from the command line. See the
63  section on <a href="code_management.html#svn_gui_commands">GUI Commands</a>
64  for further information.</p>
65
66  <p><strong>Configure your editor for Subversion</strong></p>
67
68  <p>When you attempt to create a branch or commit changes to the repository,
69  you will normally be prompted to edit your commit log message using a text
70  editor. The system chooses its editor by searching for a non-empty string
71  through a hierarchy of environment variables in this order: SVN_EDITOR,
72  VISUAL, and EDITOR. If none of these environment variables are set, the
73  default is to use <em>nedit</em>. If you set your editor with an environment
74  variable, it is worth bearing in mind that it must be able to run in the
75  foreground. For example, you can add one of the followings in your
76  <tt>$HOME/.kshrc</tt> (Korn) or <tt>$HOME/.bashrc</tt> (Bash):</p>
77  <pre>
78# GVim
79export SVN_EDITOR='gvim -f'
80
81# Emacs
82export SVN_EDITOR=emacs
83
84# NEdit client "nc"
85export SVN_EDITOR='nc -wait'
86</pre>
87
88  <p><strong>Register your user name</strong></p>
89
90  <p>At the Met Office, most projects managed by FCM grant write accesses to
91  their Subversion repositories and Trac ticket create/modify privileges to
92  authorised users only. If you are developing code for a project for the first
93  time, please contact the system manager of the project, who will arrange with
94  the FCM team to put your user name in the register.</p>
95
96  <p><strong>Configure your email address in Trac</strong></p>
97
98  <p>Trac can be configured to automatically email the owner and reporter of any
99  ticket whenever there are changes to that ticket (and we would expect most
100  systems to be configured in this way). You should check that the settings for
101  your name and e-mail address are correct. To do this you need to go to the
102  Settings page once you are logged into Trac. (Click on &lt;Settings&gt; just
103  above the menu bar). Check that your settings are entered correctly. Note: at
104  the Met Office, these settings are set up and maintained automatically, and so
105  you should report any errors to the FCM team.</p>
106
107  <p><strong>Configure your web browser</strong></p>
108
109  <p>FCM assumes that you are using Firefox as your default web browser. If you
110  use another web browser such as Mozilla, you should configure it in your
111  <tt>$HOME/.fcm</tt> file. See the section on <a href=
112  "command_ref.html#fcm_svn_trac">fcm trac</a> for further information.</p>
113
114  <h2><a name="tutorial">Tutorial</a></h2>
115
116  <h3><a name="tutorial_intro">Introduction</a></h3>
117
118  <p>This tutorial leads you through the basics of using FCM to make changes to
119  your source code, and demonstrates the recommended practices for working with
120  it. A tutorial Subversion repository, with its own Trac system, is available
121  for you to practice for working with the FCM system. You will work through
122  the following activities:</p>
123
124  <ul>
125    <li><a href="#tutorial_create-ticket">Create a new ticket</a></li>
126
127    <li><a href="#tutorial_launch-gui">Launch the GUI</a></li>
128
129    <li><a href="#tutorial_create-branch">Create a branch</a></li>
130
131    <li><a href="#tutorial_checkout">Checkout a working copy</a></li>
132
133    <li><a href="#tutorial_change">Make changes to files in your working
134    copy</a></li>
135
136    <li><a href="#tutorial_commit">Commit your changes to the
137    repository</a></li>
138
139    <li><a href="#tutorial_extract">Test your changes</a></li>
140
141    <li><a href="#tutorial_merge">Merge changes from the trunk and resolve
142    conflicts</a></li>
143
144    <li><a href="#tutorial_review-ticket">Review changes</a></li>
145
146    <li><a href="#tutorial_merge-back">Commit to the trunk</a></li>
147
148    <li><a href="#tutorial_extra-extract">Extra activities on the extract and
149    build systems</a></li>
150
151    <li><a href="#tutorial_delete-branch">Delete your branch</a></li>
152
153    <li><a href="#tutorial_delete-final-comments">Final comments</a></li>
154  </ul>
155
156  <p>We recommend that you create a work area in your filespace, for example,
157  <tt>$HOME/tutorial/work</tt> for your working copy, and
158  <tt>$HOME/tutorial/build</tt> for your build.</p>
159
160  <p>If you have not already done so, you should set up your desktop environment
161  as described above in the <a href="#setup">How to set yourself up to run
162  FCM</a> section.</p>
163
164  <p>It is also worth knowing that the <a href=
165  "http://svnbook.red-bean.com/en/1.2/">Subversion Book</a> is a great source
166  of reference of Subversion features. In particular, the <a href=
167  "http://svnbook.red-bean.com/en/1.2/svn.basic.html">Basic Concepts</a> and
168  <a href="http://svnbook.red-bean.com/en/1.2/svn.tour.html">Guided Tour</a>
169  chapters are well worth reading.</p>
170
171  <h3><a name="tutorial_create-ticket">Create a new ticket</a></h3>
172
173  <p><em>Trac is an integrated web-based issue tracker and wiki system. You
174  will use it to manage and keep track of changes in your project. The issue
175  tracker is called the ticket system. When you want to report a problem or
176  submit a change request, you will create a new ticket. In a typical
177  situation, you and/or your colleagues will make changes to your system in
178  order to resolve the problem or change request, and you will monitor these
179  changes via the ticket.</em></p>
180
181  <p>After completing this sub-section, you will learn how to:</p>
182
183  <ul>
184    <li>launch a Trac system,</li>
185
186    <li>create a new Trac ticket,</li>
187
188    <li>search for a Trac ticket, and</li>
189
190    <li>accept a Trac ticket.</li>
191  </ul>
192
193  <p>Further reading:</p>
194
195  <ul>
196    <li><a href="overview.html">System Overview</a></li>
197
198    <li>Code Management System &gt; <a href=
199    "code_management.html#svn_basic">Basic Command Line Usage</a></li>
200
201    <li>Code Management System &gt; <a href="code_management.html#trac">Using
202    Trac</a></li>
203
204    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm_svn_trac">fcm
205    trac</a></li>
206  </ul>
207
208  <h4>Launch a Trac system</h4>
209
210  <p>To launch the Trac system for the tutorial: type and <span class=
211  "mono">&lt;Enter&gt;</span> the following command:</p>
212  <pre>
213(SHELL PROMPT)$ fcm trac fcm:tutorial
214</pre>
215
216  <p>This is probably the first time you have used the <tt>fcm</tt> command.
217  The command has the general syntax:</p>
218  <pre>
219fcm &lt;sub-command&gt; [&lt;options...&gt;] &lt;arguments&gt;
220</pre>
221
222  <p>For example, if you type <tt>fcm help</tt>, it will display a listing of
223  what sub-commands are available, and if you type <tt>fcm help
224  &lt;sub-command&gt;</tt>, it will display help for that particular
225  sub-command.</p>
226
227  <p>The <tt>trac</tt> sub-command launches the corresponding Trac system
228  browser for a Subversion URL specified in your argument. In this case, we are
229  asking it to display the Trac system browser for the tutorial. The argument
230  <tt>fcm:tutorial</tt> is a FCM URL keyword and will be expanded by FCM into a
231  real Subversion URL (e.g. <tt>svn://fcm1/tutorial_svn/tutorial</tt>). You are
232  encouraged to use FCM URL keywords throughout the tutorial, as it will save
233  you a lot of typing.</p>
234
235  <p>Note: Although we use the Trac system as a browser for a Subversion
236  repository, they do not interact in any other ways. Having access to a Trac
237  system does not guarantee the same privilege to a Subversion repository. In
238  particular, you should note the differences between the URLs of a Subversion
239  repository path and its equivalence in a Trac browser.</p>
240
241  <p>There are other ways to launch the Trac system for a project. If you know
242  its URL, you can launch the Trac system by entering it in the address box of
243  your favourite browser. If you often access a Trac system for a particular
244  project, you should bookmark it in your favourite browser.</p>
245
246  <h4>Create a new Trac ticket</h4>
247
248  <p>Click on <span class="mono">&lt;Login&gt;</span> just above the menu bar,
249  enter your Unix/Linux user ID as your user name and leave the password empty.
250  Then click on <span class="mono">&lt;OK&gt;</span> to proceed.</p>
251
252  <p>Once you have logged in, the <span class="mono">&lt;New Ticket&gt;</span>
253  link will become available on the menu bar. Click on it to display a new
254  ticket form, where you can enter details about your problem or change
255  request. In the tutorial, it does not matter what you enter, but you should
256  feel free to play around with wiki formatting when entering the "Full
257  description". (Click on <span class="mono">&lt;WikiFormatting&gt;</span> to
258  see how you can use it.) For example:</p>
259
260  <ul>
261    <li>Short summary:
262      <pre>
263Tutorial to change repository files and resolve conflicts with the trunk
264</pre>
265    </li>
266
267    <li>Full description:
268      <pre>
269In this tutorial, I shall:
270 1. try out the FCM GUI and its functions
271 2. play with WikiFormatting in Trac tickets     
272 3. create a branch and checkout a working copy
273 4. make changes to files in it
274 5. commit my changes and assign the ticket for review
275 6. record the review and assign the ticket back to the author
276 7. merge in the trunk, and resolve any conflicts
277 8. merge my changes back to the trunk
278 9. close the ticket
279 10. delete my branch
280</pre>
281    </li>
282
283    <li>Feel free to select an option you desire for each of the other ticket
284    properties: Type, Component, Priority, Version, Milestone and
285    Severity.</li>
286  </ul>
287
288  <p>At the bottom of the page, click the <span class=
289  "mono">&lt;Preview&gt;</span> button to see what the description would look
290  like. When you are happy, click the <span class="mono">&lt;Submit
291  changes&gt;</span> button. Trac will create the new ticket and return it in a
292  state where you can append to it.</p>
293
294  <h4>Search for a Trac ticket</h4>
295
296  <p>You should remember the number of your new ticket, as you will have to
297  revisit it later.</p>
298
299  <p>In real work, it is often not practical to have to remember the numbers of
300  all the tickets you have created. Trac provides a powerful custom query for
301  searching a ticket. You can search for the ticket you have just created by
302  clicking the <span class="mono">&lt;View Tickets&gt;</span> link. Feel free
303  to play with the custom query tool. Add or remove filters and try grouping
304  your results by different categories.</p>
305
306  <p>In addition, you can search your ticket using the keyword <span class=
307  "mono">&lt;Search&gt;</span> utility at the top right hand corner of each
308  Trac page. (If you enter <tt>#&lt;number&gt;</tt> in the search box, it will
309  take you directly to that ticket.) In the tutorial, however, it may be
310  easiest if you simply leave the tutorial Trac system open, so that you do not
311  have to login again when you come back to your ticket.</p>
312
313  <h4>Accept Trac ticket</h4>
314
315  <p>The status of the ticket is <em>new</em>. When you start working on a
316  problem reported in a ticket or when you are reviewing changes for a
317  colleague, it is often good practice to "accept" the ticket to indicate that
318  you are working on it. For the purpose of the tutorial, however, it is
319  entirely optional whether you accept the ticket or not, since you know you
320  will be doing all the work any way.</p>
321
322  <p>To accept a ticket, click on <span class="mono">&lt;accept
323  ticket&gt;</span> in the <em>Action</em> box at the bottom of the page, and
324  then click on <span class="mono">&lt;Submit changes&gt;</span>.</p>
325
326  <h3><a name="tutorial_launch-gui">Launch the GUI</a></h3>
327
328  <p><em>The FCM GUI is a simple graphical user interface for some of the
329  common code management commands. The examples in this tutorial are all based
330  on the GUI. However, you can skip this section and use only the command line
331  if that is what you prefer. An appropriate command line usage will be given
332  following each GUI example.</em></p>
333
334  <p>After completing this sub-section, you will learn how to:</p>
335
336  <ul>
337    <li>launch the GUI from the command line, and</li>
338
339    <li>launch the GUI from Konqueror.</li>
340  </ul>
341
342  <p>Further reading:</p>
343
344  <ul>
345    <li>Code Management System &gt; <a href=
346    "code_management.html#svn_gui">Using the GUI</a></li>
347
348    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm_gui">fcm
349    gui</a></li>
350  </ul>
351
352  <h4>Launch the GUI from the command line</h4>
353
354  <p>You can launch the GUI from the command line. Change directory to your
355  work area and then type <tt>fcm gui</tt>.</p>
356
357  <h4>Launch the GUI from Konqueror</h4>
358
359  <p>Alternatively, open Konqueror and navigate to your work area. Right-click
360  in the file-manager window to bring up a menu. Select <em>Open with</em> &gt;
361  <em>FCM GUI</em>.</p>
362
363  <h3><a name="tutorial_create-branch">Create a branch</a></h3>
364
365  <p><em>You create a branch by making a copy of your project at a particular
366  revision. Most often, this will be a particular revision of the trunk, i.e.
367  the main branch/development line in your project.  A branch resides in the
368  repository. It allows you to work in parallel with your colleagues without
369  affecting one another, while keeping your changes under version
370  control.</em></p>
371
372  <p>After completing this sub-section, you will learn how to:</p>
373
374  <ul>
375    <li>create a branch in a Subversion repository, and</li>
376
377    <li>update a ticket with a link to a branch.</li>
378  </ul>
379
380  <p>Further reading:</p>
381
382  <ul>
383    <li>Code Management System &gt; Branching &amp; Merging &gt; <a href=
384    "code_management.html#svn_branching_create">Creating Branches</a></li>
385
386    <li>Code Management Working Practices &gt; <a href=
387    "working_practices.html#branching">Branching &amp; Merging</a></li>
388
389    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm_svn_br">fcm
390    branch</a></li>
391  </ul>
392
393  <h4>Create a branch in a Subversion repository</h4>
394
395  <p>In the FCM GUI, click on <span class="mono">&lt;Branch&gt;</span> on the
396  top menu bar of the GUI. Check the <span class="mono">&lt;create&gt;</span>
397  radio button and configure your branch details as follow:</p>
398
399  <ul>
400    <li>Enter <tt>fcm:tutorial</tt> for the URL of the tutorial
401    repository.</li>
402
403    <li>Enter the short branch name. This must contain only alpha-numeric
404    characters and/or underscores, e.g. <tt>tutorial</tt>.</li>
405
406    <li>Enter <tt>1</tt> for the source revision. The trunk was last changed at
407    revision 2. To facilitate the generation of conflicts when you merge with
408    it, you will branch from revision 1 of the trunk.</li>
409
410    <li>Set the branch type. In this case click on <span class=
411    "mono">&lt;test::user&gt;</span>. This will ensure the branch you create is
412    a user test branch.</li>
413
414    <li>Leave the source type as <span class="mono">&lt;trunk&gt;</span> and
415    the prefix option as <span class="mono">&lt;normal&gt;</span>.</li>
416
417    <li>Enter the related Trac ticket number for the ticket you created
418    earlier.</li>
419
420    <li>As this is probably the first time you access the tutorial repository,
421    you should also enter <tt>--password ""</tt> (i.e. <tt>--password</tt>
422    followed by a pair of quotes) in the "Other Options" entry box.</li>
423  </ul>
424
425  <p>Click on <span class="mono">&lt;Run&gt;</span> when you are ready.</p>
426
427  <p><em>Command line alternative</em>: use the <tt>fcm branch --create</tt> (or
428  simply <tt>fcm br -c</tt>) command. E.g.:</p>
429  <pre>
430(SHELL PROMPT)$ fcm br -c -n tutorial -r 1 --type test -k 2 fcm:tutorial
431</pre>
432
433  <p class="image"><img src="create_branch.png" border="0" alt=
434  "create my branch"></p>
435
436  <p>You will be prompted to edit the message log file. A standard template is
437  automatically supplied for the commit. However, if you want to add extra
438  comment for the branch, please do so <strong>above</strong> the line that
439  says "<tt>--This line will be ignored and those below will be inserted
440  automatically--</tt>". When you are ready, save your change and exit the
441  editor. Answer <span class="mono">&lt;Yes&gt;</span> when you are prompted to
442  go ahead and create the branch.</p>
443
444  <p>Note: If you are on the command line, the Subversion command will prompt
445  you for a password the first time you access a repository. The password will
446  normally be cached by the client, and you will not have to specify a password
447  on subsequent access. If you are using the GUI, please refer to the section on
448  <a href="code_management.html#svn_gui_commands">GUI Commands</a> in the next
449  chapter for further information.</p>
450
451  <p>When creating branches for the first time, you will notice that FCM will
452  create and commit any missing sub-directories it needs to set up your branch
453  inside the repository, before creating your branch and commiting it.</p>
454
455  <p>Take a note of the revision number the branch was created at, and its
456  branch name. (The revision number is the number following the last output
457  that says "Committed revision". In the example above, the branch created at
458  <tt>[5]</tt> is called <tt>branches/test/frsn/r1_tutorial</tt>, which is a
459  branch of the <tt>tutorial</tt> project in the
460  <tt>svn://fcm1/tutorial_svn</tt> repository.)</p>
461
462  <h4>Update your ticket with a link to your branch</h4>
463
464  <p>If you wish, you can update your ticket with details of the branch. Note
465  that this step is entirely optional. It is useful for developments which will
466  take a long time to complete. For short lived branches, this step is probably
467  unnecessary.</p>
468
469  <p>In the ticket you have created, refer to the revision number in the
470  <em>Add/Change</em> box, for example:</p>
471  <pre>
472Created the branch [source:tutorial/branches/test/frsn/r1_tutorial@5] at [5].
473</pre>
474
475  <p>Note:</p>
476
477  <ul>
478    <li><tt>[source:tutorial/branches/test/frsn/r1_tutorial@5]</tt> is a Trac
479    wiki link. In this syntax, you do not have to put in the root URL, (e.g.
480    <tt>svn://fcm1/tutorial_svn/</tt>), but you should specify your branch
481    using the project name (<tt>tutorial</tt>), the branch name
482    (<tt>branches/test/frsn/r1_tutorial</tt>), and a revision number. Trac will
483    translate this into a link to that branch.</li>
484
485    <li>Trac will translate the syntax <tt>[&lt;number&gt;]</tt> into a link to
486    the numbered changeset.</li>
487  </ul>
488
489  <p>Click on &lt;Preview&gt; and check that the links work correctly, and on
490  <span class="mono">&lt;Submit changes&gt;</span> when you are ready.</p>
491
492  <h3><a name="tutorial_checkout">Checkout a working copy</a></h3>
493
494  <p><em>A Subversion working copy is an ordinary directory tree on your local
495  system, containing a collection of files. It is your private working area in
496  which you can make changes before publishing them back to the repository. You
497  create a working copy by using the checkout command on some subtree of the
498  repository.</em></p>
499
500  <p>After completing this sub-section, you will learn how to:</p>
501
502  <ul>
503    <li>checkout a Subversion working copy.</li>
504  </ul>
505
506  <p>Further reading:</p>
507
508  <ul>
509    <li>Code Management System &gt; <a href=
510    "code_management.html#svn_concepts">Basic Concepts</a></li>
511
512    <li>FCM Command Reference &gt; <a href=
513    "command_ref.html#fcm_svn_other">Other Subversion Commands</a></li>
514  </ul>
515
516  <h4>Checkout a Subversion working copy</h4>
517
518  <p>Click on <span class="mono">&lt;Checkout&gt;</span> in the GUI, and enter
519  the URL of your branch, e.g. <tt>fcm:tutorial_br/test/frsn/r1_tutorial</tt>.
520  Note:</p>
521
522  <ul>
523    <li>In the example, we have replaced the leading part of the Subversion URL
524    <tt>svn://fcm1/tutorial_svn/tutorial/branches</tt> with the FCM repository
525    keyword <tt>fcm:tutorial_br</tt>. This is mainly to save you from having to
526    type in the full URL. However, you may find it easier to copy-and-paste the
527    full Subversion URL from the output generated when you created the
528    branch.</li>
529
530    <li>If you do not specify a local directory PATH in the <tt>checkout</tt>
531    command, it will create a working copy in your current working directory,
532    using the basename of the URL you are checking out. For example, when you
533    checkout the branch you have just created, the command should create the
534    working copy in <tt>$PWD/r1_tutorial</tt>. Make a note of the location of
535    your working copy, in case you forget where you have put it.</li>
536
537    <li>If you do not specify a revision to checkout, it will checkout the
538    HEAD, i.e. the latest, revision.</li>
539  </ul>
540
541  <p>Click on <span class="mono">&lt;Run&gt;</span> - a working copy pointing
542  to your branch will be created. The GUI will automatically change directory
543  to the top of your new working copy.</p>
544
545  <table class="pad" summary="branch checkout example" border="1" width="100%">
546    <tr>
547      <th>Example output, checking out the branch</th>
548    </tr>
549
550    <tr>
551      <td>
552        <pre>
553=&gt; svn co --revision HEAD svn://fcm1/tutorial_svn/tutorial/branches/test/frsn/r1_tutorial
554A    r1_tutorial/cfg
555A    r1_tutorial/cfg/ext.cfg
556A    r1_tutorial/doc
557A    r1_tutorial/doc/hello.html
558A    r1_tutorial/src
559A    r1_tutorial/src/subroutine
560A    r1_tutorial/src/subroutine/hello_c.c
561A    r1_tutorial/src/subroutine/hello_sub.f90
562A    r1_tutorial/src/module
563A    r1_tutorial/src/module/hello_constants.f90
564A    r1_tutorial/src/program
565A    r1_tutorial/src/program/hello.f90
566Checked out revision 5.
567</pre>
568      </td>
569    </tr>
570  </table>
571
572  <p><em>Command line alternative</em>: use the <tt>fcm checkout</tt> (or simply
573  <tt>fcm co</tt>) command. E.g.:</p>
574  <pre>
575(SHELL PROMPT)$ fcm co fcm:tutorial_br/test/frsn/r1_tutorial
576</pre>
577
578  <h3><a name="tutorial_change">Make changes to files in your working
579  copy</a></h3>
580
581  <p><em>Subversion provides various useful commands to help you monitor your
582  working copy. The most useful ones are "diff", "revert" and "status". You
583  will also find "add", "copy", "delete" and "move" useful when you are
584  rearranging your files and directories.</em></p>
585
586  <p>After completing this sub-section, you will learn how to:</p>
587
588  <ul>
589    <li>make and revert changes,</li>
590
591    <li>add and remove files,</li>
592
593    <li>inspect the status of a working copy, and</li>
594
595    <li>display changes in a working copy.</li>
596  </ul>
597
598  <p>Further reading:</p>
599
600  <ul>
601    <li>Code Management System &gt; <a href=
602    "code_management.html#svn_basic">Basic Command Line Usage</a></li>
603
604    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm_svn_add">fcm
605    add</a>, <a href="command_ref.html#fcm_svn_diff">fcm diff</a>, <a href=
606    "command_ref.html#fcm_svn_delete">fcm delete</a>, <a href=
607    "command_ref.html#fcm_svn_other">Other Subversion Commands</a></li>
608  </ul>
609
610  <h4>Make and revert changes</h4>
611
612  <p>For the later part of the tutorial to work, you must make the following
613  modification:</p>
614
615  <ul>
616    <li>Change to the "<tt>src/module/</tt>" sub-directory in your working
617    copy.</li>
618
619    <li>Edit <b>hello_constants.f90</b>, using your favourite editor, and
620    change: <em>"Hello World!"</em> to <em>"Hello Earthlings!"</em>. Save your
621    change and exit the editor.</li>
622  </ul>
623
624  <p>Try the following so that you know how to restore a changed file:</p>
625
626  <ul>
627    <li>Change to the "<tt>src/subroutine/</tt>" directory of your working
628    copy.</li>
629
630    <li>Make a change in file <b>hello_c.c</b>, using your favourite
631    editor.</li>
632
633    <li>In the GUI, click on <span class="mono">&lt;Status&gt;</span> and then
634    on <span class="mono">&lt;Run&gt;</span> to see that you have
635    <u>M</u>odified this file. (Alternatively, you can type "<tt>fcm
636    status</tt>" on the command line.)</li>
637
638    <li>Run the <em>revert</em> command to get the file back unmodified:
639      <pre>
640(SHELL PROMPT)$ fcm revert hello_c.c
641</pre>
642    </li>
643  </ul>
644
645  <h4>Add and remove files</h4>
646
647  <p>You may also want to try the following FCM commands in your <tt>doc/</tt>
648  sub-directory. You can safely make changes here since they will not interfere
649  with your code changes.</p>
650
651  <ul>
652    <li>change to the "doc/" directory of your working copy.</li>
653
654    <li>Echo some text into a new file and then run the <em>add</em> command,
655    which lets the repository know you're adding a new file at the next commit.
656    For example:
657      <pre>
658(SHELL PROMPT)$ echo 'Some text' &gt;new_file.txt
659(SHELL PROMPT)$ fcm add new_file.txt
660</pre>
661    </li>
662
663    <li>Make a copy of <em>hello.html</em> and remove the original, using the
664    <em>copy</em> and <em>delete</em> commands. For example:
665      <pre>
666(SHELL PROMPT)$ fcm copy hello.html add.html
667(SHELL PROMPT)$ fcm delete hello.html
668</pre>
669    </li>
670
671    <li>You can use a simple <em>move</em> sub-command for the above
672    <em>copy</em> and <em>delete</em>.</li>
673  </ul>
674
675  <h4>Inspect the status of a working copy</h4>
676
677  <p>In the GUI, click on <span class="mono">&lt;Status&gt;</span> and then on
678  <span class="mono">&lt;Run&gt;</span> to see what has changed:</p>
679
680  <table class="pad" summary="status example 1" border="1" width="100%">
681    <tr>
682      <th>Example output, status in a working copy</th>
683    </tr>
684
685    <tr>
686      <td>
687        <pre>
688=&gt; svn status
689D      doc/hello.html
690A      doc/new_file.txt
691A  +   doc/add.html
692M      src/module/hello_constants.f90
693</pre>
694      </td>
695    </tr>
696  </table>
697
698  <p><em>Command line alternative</em>: use the <tt>fcm status</tt> (or simply
699  <tt>fcm st</tt>) command.</p>
700
701  <p>This confirms the actions you have taken. You have <u>D</u>eleted a file,
702  <u>A</u>dded a new file, <u>A</u>dded a file with history (<tt>+</tt>) and
703  <u>M</u>odified another. It also confirms the action of the <em>revert</em>
704  command.</p>
705
706  <h4>Display changes in a working copy</h4>
707
708  <p>You can view the changes you have made to your working copy. In the GUI,
709  click on <span class="mono">&lt;Diff&gt;</span> and then on <span class=
710  "mono">&lt;Run&gt;</span>.</p>
711
712  <p><em>Command line alternative</em>: use the <tt>fcm diff --graphical</tt>
713  (or simply <tt>fcm di -g</tt>) command.</p>
714
715  <p>A listing of the files you have changed will be displayed, and a graphical
716  diff tool will open up for each modified file.</p>
717
718  <h3><a name="tutorial_commit">Commit your changes to the repository</a></h3>
719
720  <p><em>The change in your working copy remains local until you commit it to
721  the repository where it becomes permanent. If you are planning to make a
722  large number of changes, you are encouraged to commit regularly to your
723  branch at appropriate intervals.</em></p>
724
725  <p>After completing this sub-section, you will learn how to:</p>
726
727  <ul>
728    <li>commit your changes, and</li>
729
730    <li>inspect your changes using Trac.</li>
731  </ul>
732
733  <p>Further reading:</p>
734
735  <ul>
736    <li>Code Management System &gt; <a href=
737    "code_management.html#svn_basic">Basic Command Line Usage</a></li>
738
739    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm_svn_ci">fcm
740    commit</a></li>
741  </ul>
742
743  <h4>Commit changes</h4>
744
745  <p>In the GUI, click on <span class="mono">&lt;Commit&gt;</span> and then on
746  <span class="mono">&lt;Run&gt;</span>.</p>
747
748  <p><em>Command line alternative</em>: use the <tt>fcm commit</tt> (or simply
749  <tt>fcm ci</tt>) command.</p>
750
751  <p>A text editor will appear to allow you to edit the commit message. You
752  must add a commit message to describe your change <strong>above</strong> the
753  line that says "<tt>--This line, and those below, will be ignored--</tt>". (A
754  suggestion is given as the highlighted text in the example below.) Your
755  commit will fail if you do not enter a commit message.</p>
756
757  <p>Save your change and exit the editor. Answer <span class=
758  "mono">&lt;Yes&gt;</span> when you are prompted to confirm the commit. For
759  example:</p>
760
761  <table class="pad" summary="status example 1" border="1" width="100%">
762    <tr>
763      <th>Example output, commit my changes to the repository</th>
764    </tr>
765
766    <tr>
767      <td>
768        <pre>
769Starting nedit to create commit message ...
770Commit message is as follows:
771------------------------------------------------------------------------
772<font color="purple">In my tutorial branch, for #2:
773  1. Moved hello.html to add.html, and created a new document '''new_file.txt'''
774  2. Changed greeting in hello_constants.f90 to ''Hello Earthlings!''</font>
775--This line, and those below, will be ignored--
776[Project: tutorial]
777[Branch : branches/test/frsn/r1_tutorial]
778[Sub-dir: &lt;top&gt;]
779
780D      doc/hello.html
781A      doc/new_file.txt
782A  +   doc/add.html
783M      src/module/hello_constants.f90
784------------------------------------------------------------------------
785Adding         doc/add.html
786Deleting       doc/hello.html
787Adding         doc/new_file.txt
788Sending        src/module/hello_constants.f90
789Transmitting file data ..
790Committed revision 6.
791Performing update to make sure your working copy is at this new revision ...
792At revision 6.
793</pre>
794      </td>
795    </tr>
796  </table>
797
798  <h4>Inspect changes using Trac</h4>
799
800  <p>Click on <span class="mono">&lt;Timeline&gt;</span> in Trac. Drill down to
801  your changeset and see how it appears. (Alternatively, if you enter
802  "<tt>[&lt;number&gt;]</tt>" into the search box at the top right, it will
803  take you directly to the numbered changeset.) For example:</p>
804
805  <p class="image"><img src="changeset.png" border="0" alt=
806  "commit my changes"></p>
807
808  <p>Note:</p>
809
810  <ul>
811    <li>Wiki Formatting, used in the commit message, has customised the
812    changeset message.</li>
813
814    <li>All your changes are listed.</li>
815  </ul>
816
817  <h3><a name="tutorial_extract">Test your changes</a></h3>
818
819  <p><em>You should test the changes in your branch before asking a colleague
820  to review them. FCM features a build system that allows you to build your
821  code easily. As your changes may be located in a repository branch and/or a
822  working copy, you should work with the extract system to extract the correct
823  code to build. The extract system allows you to extract code from the
824  repository, combining changes in different branches and your working copy,
825  before generating a configuration file and a suitable source tree for feeding
826  into the build system.</em></p>
827
828  <p><em>In this sub-section of the tutorial, you will be shown how to extract
829  and build the code from your branch. (There are some <a href=
830  "#tutorial_extra-extract">extra activities on the extract and build
831  systems</a> in a later sub-section of the tutorial should you want to explore
832  the extract and build systems in more depth.) In the example here, the
833  extract and build systems will be shown to you in their simplest form. In
834  real life, the managers of the systems you are developing code for will
835  provide you with more information on how to extract and build their
836  systems.</em></p>
837
838  <p>After completing this sub-section, you will learn how to:</p>
839
840  <ul>
841    <li>set up a simple extract configuration file, and</li>
842
843    <li>perform simple extracts and builds.</li>
844  </ul>
845
846  <p>Further reading:</p>
847
848  <ul>
849    <li><a href="extract.html">The Extract System</a></li>
850
851    <li><a href="build.html">The Build System</a></li>
852  </ul>
853
854  <p>You should extract and build your code in a different directory to your
855  working copy. For example, you may want to create a sub-directory
856  <tt>tutorial/build/</tt> in <tt>$HOME</tt> and change to it:</p>
857  <pre>
858(SHELL PROMPT)$ mkdir -p $HOME/tutorial/build
859(SHELL PROMPT)$ cd $HOME/tutorial/build
860</pre>
861
862  <h4>Set up an extract configuration file</h4>
863
864  <p>To set up an extract configuration file from scratch, launch your
865  favourite editor and add the following lines:</p>
866
867  <table class="pad" summary="extract config example, branch" border="1" width=
868  "100%">
869    <tr>
870      <th>Example extract configuration, extract from a branch</th>
871    </tr>
872
873    <tr>
874      <td>
875        <pre>
876# Extract configuration, format version 1.0
877cfg::type              ext
878cfg::version           1.0
879
880# Extract destination root directory
881dest::rootdir          $HOME/tutorial/build
882
883# Location of the source in the "r1_tutorial" branch
884repos::tutorial::base  fcm:tutorial_br/test/$LOGNAME/r1_tutorial
885
886# Extract all sub-directories under the above URL
887expsrc::tutorial::base src
888
889# Fortran compiler, C compiler and linker commands respectively
890# You may need to redefine these for different platforms
891bld::tool::fc          ifc
892bld::tool::cc          gcc
893bld::tool::ld          ifc
894</pre>
895      </td>
896    </tr>
897  </table>
898
899  <p>Note:</p>
900
901  <ul>
902    <li>The "<tt>dest::rootdir</tt>" declaration is set to
903    <tt>$HOME/tutorial/build</tt>. If you decide to extract to a different
904    directory, you should modify its value.</li>
905
906    <li>Similarly, the "<tt>repos::tutorial::base</tt>" declaration is set to
907    <tt>fcm:tutorial_br/test/$LOGNAME/r1_tutorial</tt>. If you have named your
908    branch differently, you should modify its value.</li>
909  </ul>
910
911  <p>Save the file as "<tt>ext.cfg</tt>" and exit your editor.</p>
912
913  <h4>Perform an extract and a build</h4>
914
915  <p>Issue the command "<tt>fcm extract</tt>" and you should get an output
916  similar to the following:</p>
917
918  <table class="pad" summary="extract example, branch" border="1" width="100%">
919    <tr>
920      <th>Example output, extract from a branch</th>
921    </tr>
922
923    <tr>
924      <td>
925        <pre>
926(SHELL PROMPT)$ fcm extract
927Extraction started on Thu Oct 27 13:54:06 2005.
928Config file (ext): /net/home/h01/frsn/tutorial/build/ext.cfg
929-&gt;Extract: start
930Number of directories created    : 4
931Number of updated files          : 4
932-&gt;Extract: 1 second
933-&gt;TOTAL  : 1 second
934Extraction finished on Thu Oct 27 13:54:07 2005.
935</pre>
936      </td>
937    </tr>
938  </table>
939
940  <p>If nothing goes wrong, you should end up with the sub-direcories
941  "<tt>src/</tt>" and "<tt>cfg/</tt>" in your working directory. The
942  "<tt>src/</tt>" contains a source tree to be built, and "<tt>cfg/</tt>" should
943  contain two configuration files: "<tt>ext.cfg</tt>" and "<tt>bld.cfg</tt>".
944  The former is an expanded version of your extract configuration file and the
945  latter is a build configuration file. You can now build your code by running
946  the "<tt>fcm build</tt>" command:</p>
947
948  <table class="pad" summary="build example, branch" border="1" width="100%">
949    <tr>
950      <th>Example output, build</th>
951    </tr>
952
953    <tr>
954      <td>
955        <pre>
956(SHELL PROMPT)$ fcm build 2&gt;err
957Build command started on Fri Oct 14 09:15:38 2005.
958-&gt;gt;Setup              : start
959Config file (bld): /net/home/h01/frsn/tutorial/build/cfg/bld.cfg
960-&gt;Setup              : 0 second
961-&gt;Pre-process        : start
962-&gt;Pre-process        : 0 second
963-&gt;Scan dependency    : start
964Scanned files in 3 package(s) for dependency
965Updated make rules for 3 package(s).
966Updated Makefile: /net/home/h01/frsn/tutorial/build/bld/Makefile
967-&gt;Scan dependency    : 1 second
968-&gt;Generate interface : start
969Number of generated interfaces: 1
970-&gt;Generate interface : 0 second
971-&gt;Make               : start
972ifc -o hello_constants.o -I/home/h01/frsn/tutorial/build/inc -c
973  /home/h01/frsn/tutorial/build/src/tutorial/src/module/hello_constants.f90
974ifc -o hello.o -I/home/h01/frsn/tutorial/build/inc -c
975  /home/h01/frsn/tutorial/build/src/tutorial/src/program/hello.f90
976ifc -o hello_sub.o -I/home/h01/frsn/tutorial/build/inc -c
977  /home/h01/frsn/tutorial/build/src/tutorial/src/subroutine/hello_sub.f90
978gcc -o hello_c.o -I/home/h01/frsn/tutorial/build/inc -c
979  /home/h01/frsn/tutorial/build/src/tutorial/src/subroutine/hello_c.c
980ifc -o hello.exe /home/h01/frsn/tutorial/build/obj/hello.o
981  -L/home/h01/frsn/tutorial/build/lib -l__fcm__hello
982-&gt;Make               : 3 seconds
983-&gt;TOTAL              : 4 second
984Build command finished on Fri Oct 14 09:15:42 2005.
985</pre>
986      </td>
987    </tr>
988  </table>
989
990  <p>The executable you have built is "<tt>hello.exe</tt>", which is located in
991  the "<tt>bin/</tt>" sub-directory. You can test your executable by running
992  it. You should an output similar to the following:</p>
993
994  <table class="pad" summary="build example run, working copy" border="1"
995  width="100%">
996    <tr>
997      <th>Example output, running the build</th>
998    </tr>
999
1000    <tr>
1001      <td>
1002        <pre>
1003(SHELL PROMPT)$ bin/hello.exe
1004Hello: Hello Earthlings!
1005Hello_Sub: Hello Earthlings!
1006Hello_Sub: maximum integer: 2147483647
1007Hello_C: Hello World!
1008</pre>
1009      </td>
1010    </tr>
1011  </table>
1012
1013  <h3><a name="tutorial_merge">Merge changes from the trunk and resolve
1014  conflicts</a></h3>
1015
1016  <p><em>Your branch is normally isolated from other development lines in your
1017  project. However, at some point during your development, you may need to merge
1018  your changes with those of your colleagues. In some cases, it is desirable to
1019  merge changes regularly from the trunk to keep your branch up to date with the
1020  latest development. The automatic merge provided by FCM allows you to do this
1021  easily.</em></p>
1022
1023  <p><em>A merge results in a conflict if changes being applied to a file
1024  overlap. FCM uses a graphical merge tool to help you resolve conflicts in text
1025  files.</em></p>
1026
1027  <p>After completing this sub-section, you will learn how to:</p>
1028
1029  <ul>
1030    <li>merge changes from the trunk into your working copy, and</li>
1031
1032    <li>resolve conflicts in your working copy.</li>
1033  </ul>
1034
1035  <p>Further reading:</p>
1036
1037  <ul>
1038    <li>Code Management System &gt; Basic Command Line Usage &gt; <a href=
1039    "code_management.html#svn_basic_conflicts">Resolving Conflicts</a></li>
1040
1041    <li>Code Management System &gt; <a href=
1042    "code_management.html#svn_branching">Branching &amp; Merging</a></li>
1043
1044    <li>Code Management Working Practices &gt; <a href=
1045    "working_practices.html#branching">Branching &amp; Merging</a></li>
1046
1047    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm_svn_cf">fcm
1048    conflicts</a></li>
1049
1050    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm_svn_merge">fcm
1051    merge</a></li>
1052  </ul>
1053
1054  <h4>Merge changes from the trunk into a working copy</h4>
1055
1056  <p>Change directory back to your working copy.</p>
1057
1058  <p>In the GUI, click on <span class="mono">&lt;Merge&gt;</span>. Enter
1059  "<tt>trunk</tt>" into the Source entry box and click on <span class=
1060  "mono">&lt;Run&gt;</span> to proceed.</p>
1061
1062  <p><em>Command line alternative</em>: use the <tt>fcm merge</tt> command.
1063  E.g.</p>
1064  <pre>
1065(SHELL PROMPT)$ fcm merge trunk
1066</pre>
1067
1068  <p>If there is more than one revision of the source that you can merge with,
1069  you will be prompted for the revision number you wish to merge from. You will
1070  not be prompted in this case, because there is only one revision of the
1071  source that you can merge with.</p>
1072
1073  <p>Answer <span class="mono">&lt;Yes&gt;</span> when you are prompted to go
1074  ahead with the merge.</p>
1075
1076  <table class="pad" summary="merge from trunk example" border="1" width=
1077  "100%">
1078    <tr>
1079      <th>Example output, merging changes from the trunk</th>
1080    </tr>
1081
1082    <tr>
1083      <td>
1084        <pre>
1085Available Merges From /tutorial/trunk: 2
1086About to merge in changes from tutorial/trunk@2 compared with tutorial/trunk@1
1087This merge will result in the following changes:
1088------------------------------------------------------------------------
1089U    src/subroutine/hello_c.c
1090C    src/module/hello_constants.f90
1091------------------------------------------------------------------------
1092Performing merge ...
1093U    src/subroutine/hello_c.c
1094C    src/module/hello_constants.f90
1095</pre>
1096      </td>
1097    </tr>
1098  </table>
1099
1100  <h4>Resolve conflicts in a working copy</h4>
1101
1102  <p>The "C" status indicates that the file you changed is now in conflict. If
1103  you run <tt>status</tt>, you will see extra files created by the merge, which
1104  enable you to resolve the conflict using the 3-way difference tool
1105  <em>xxdiff</em>:</p>
1106
1107  <table class="pad" summary="conflict status example" border="1" width="100%">
1108    <tr>
1109      <th>Example output, status in conflict</th>
1110    </tr>
1111
1112    <tr>
1113      <td>
1114        <pre>
1115=&gt; svn status
1116M      src/subroutine/hello_c.c
1117?      src/module/hello_constants.f90.merge-left.r1
1118?      src/module/hello_constants.f90.merge-right.r2
1119?      src/module/hello_constants.f90.working
1120C      src/module/hello_constants.f90
1121</pre>
1122      </td>
1123    </tr>
1124  </table>
1125
1126  <p>You will now have to resolve the conflicts.</p>
1127
1128  <p>In the GUI, click on <span class="mono">&lt;Conflicts&gt;</span> and then
1129  on <span class="mono">&lt;Run&gt;</span>.</p>
1130
1131  <p><em>Command line alternative</em>: use the <tt>fcm conflicts</tt> (or
1132  simply <tt>fcm cf</tt>) command.</p>
1133
1134  <p><em>xxdiff</em> comes into play:</p>
1135
1136  <p class="image"><img src="xxdiff_tutorial.png" border="0" alt=
1137  "3-way diff"></p>
1138
1139  <p>See the sub-section on <a href=
1140  "code_management.html#svn_basic_conflicts">resolving conflicts</a>, or the
1141  <em>xxdiff User's Manual (click on <span class=
1142  "mono">&lt;Help&gt;</span>)</em> to guide you through this process. (If you
1143  do not want to learn how to use <em>xxdiff</em> now, you can just select
1144  <em>Exit with ACCEPT</em> from the <em>File</em> menu. This saves the file
1145  you are merging in as the result of the merge, i.e. you have
1146  <em>accepted</em> all the changes).</p>
1147
1148  <p>On resolving the conflict, you will be asked to run "<tt>svn
1149  resolved</tt>". Answer <span class="mono">&lt;Yes&gt;</span>.</p>
1150
1151  <p>If you now run <tt>status</tt>, you will notice that these extra conflict
1152  files have disappeared.</p>
1153
1154  <table class="pad" summary="resolve conflicts example" border="1" width=
1155  "100%">
1156    <tr>
1157      <th>Example output, resolving conflicts</th>
1158    </tr>
1159
1160    <tr>
1161      <td>
1162        <pre>
1163Conflicts in file: src/module/hello_constants.f90
1164All merge conflicts resolved
1165Resolved conflicted state of 'hello_constants.f90'
1166=&gt; svn status
1167M      src/subroutine/hello_c.c
1168M      src/module/hello_constants.f90
1169</pre>
1170      </td>
1171    </tr>
1172  </table>
1173
1174  <p>It is important to remember that the <tt>merge</tt> command only applies
1175  changes to your working copy. Therefore, you must now commit the change in
1176  order for it to become permanent in the repository. Similar to other changes,
1177  it is a good practice to use <tt>diff</tt> to inspect the changes before
1178  committing.</p>
1179
1180  <p>When you run <tt>commit</tt>, you will be prompted to edit the commit log
1181  as usual. However, you may notice that a standard template is already
1182  provided for you by the <tt>merge</tt> command. In most cases, the standard
1183  message should be sufficient. However, if you want to add extra comment to
1184  the commit, please do so <strong>above</strong> the line that says
1185  "<tt>--This line will be ignored and those below will be inserted
1186  automatically--</tt>". This is useful, for example, if there were significant
1187  issues addressed in the merge.</p>
1188
1189  <h3><a name="tutorial_review-ticket">Review changes</a></h3>
1190
1191  <p><em>For the purpose of this tutorial, we assume that your changes are
1192  complete, have been tested and committed to the repository, and are now ready
1193  for review. You should assign the ticket to the reviewer and inform him/her
1194  where to find the changes you wish him/her to review. The reviewer will
1195  record any issues in the ticket, perhaps linking to other documents as
1196  required. Once completed, he/she will record the outcome in the ticket and
1197  assign it back to the you.</em></p>
1198
1199  <p>After completing this sub-section, you will learn how to:</p>
1200
1201  <ul>
1202    <li>re-assign a ticket, and</li>
1203
1204    <li>display changes in a branch.</li>
1205  </ul>
1206
1207  <p>Further reading:</p>
1208
1209  <ul>
1210    <li>Code Management System &gt; Branching &amp; Merging &gt; <a href=
1211    "code_management.html#svn_branching_info">Getting Information About
1212    Branches</a></li>
1213
1214    <li>Code Management System &gt; <a href="code_management.html#trac">Using
1215    Trac</a></li>
1216
1217    <li>Code Management Working Practices &gt; <a href=
1218    "working_practices.html#tickets">Using Tickets</a></li>
1219
1220    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm_svn_diff">fcm
1221    diff</a></li>
1222  </ul>
1223
1224  <h4>Re-assign a ticket to a reviewer</h4>
1225
1226  <p>Back in your ticket, add an appropriate comment showing where to find your
1227  changes, in the <em>Add/Change</em> box. Include the location of the branch,
1228  and its latest revision number in the comment. For example:</p>
1229
1230  <table summary="review ticket example" border="1">
1231    <tr>
1232      <td>
1233        <pre>
1234The [log:tutorial/branches/test/frsn/r1_tutorial@5:7] branch proposes changes
1235to the greeting message in hello_constants.f90. It also contains some new
1236documents.
1237
1238Fred, could you review the change, please?
1239</pre>
1240      </td>
1241    </tr>
1242  </table>
1243
1244  <p>Note: the syntax <tt>[log:tutorial/branches/test/frsn/r1_tutorial@5:7]</tt>
1245  will be translated by Trac into a link to the revision log browser to display
1246  the log between revision 5 and 7 of the
1247  <tt>branches/test/frsn/r1_tutorial</tt> branch in the <tt>tutorial</tt>
1248  project. Click on &lt;Preview&gt; and check that the
1249  link works correctly.</p>
1250
1251  <p>To re-assign a ticket to your reviewer, click on the <span class=
1252  "mono">&lt;reassign to&gt;</span> button in the <em>Action</em> box section
1253  and enter the reviewer's User ID.</p>
1254
1255  <p>When you are ready, click on <span class="mono">&lt;Submit
1256  changes&gt;</span>. In real life, if the reviewer is a registered user of the
1257  Trac system, he/she should be sent an e-mail of the review request
1258  automatically. Otherwise, you may need to inform the reviewer of the request
1259  by other means.</p>
1260
1261  <h4>Display changes in a branch</h4>
1262
1263  <p>For the purpose of this tutorial, you will act as the reviewer of the
1264  changes you have made. To review the changes in a branch, you can look at all
1265  the changes relative to its base.</p>
1266
1267  <p>In the GUI, click on <span class="mono">&lt;Diff&gt;</span>. Enter the URL
1268  of the branch (e.g. <tt>fcm:tutorial_br/test/frsn/r1_tutorial</tt>), check
1269  the box <span class="mono">&lt;Show differences relative to the base of the
1270  branch&gt;</span>, and click on <span class="mono">&lt;Run&gt;</span>.</p>
1271
1272  <p><em>Command line alternative</em>: use the <tt>fcm diff --branch</tt> (or
1273  simply <tt>fcm di -b</tt>) command. E.g.</p>
1274  <pre>
1275fcm di -b -g fcm:tutorial_br/test/frsn/r1_tutorial
1276</pre>
1277
1278  <p>You should be presented with the differences between the branch and the
1279  trunk (since the last merge).</p>
1280
1281  <h4>Reassign the ticket back to the author</h4>
1282
1283  <p>Following the review, you should record its outcome and re-assign the
1284  ticket back to the author. Enter the comment "<tt>No issues were found during
1285  the review</tt>". Click on the <span class="mono">&lt;reassign to&gt;</span>
1286  button in the <em>Action</em> box section, and enter your guest account name.
1287  Click on <span class="mono">&lt;Submit changes&gt;</span> when you are
1288  ready.</p>
1289
1290  <p>In real life, the original author will be notified by an automatic
1291  e-mail.</p>
1292
1293  <h3><a name="tutorial_merge-back">Commit to the trunk</a></h3>
1294
1295  <p><em>Your changes in the branch have been tested and reviewed. It is now
1296  time to merge and commit it to the trunk. Once you have committed your
1297  change, you will close your ticket to complete the work cycle.</em></p>
1298
1299  <p>After completing this sub-section, you will learn how to:</p>
1300
1301  <ul>
1302    <li>use the <tt>switch</tt> command,</li>
1303
1304    <li><tt>merge</tt> and <tt>commit</tt> your changes into the trunk,
1305    and</li>
1306
1307    <li>close a ticket</li>
1308  </ul>
1309
1310  <p>Further reading:</p>
1311
1312  <ul>
1313    <li>Code Management System &gt; <a href=
1314    "code_management.html#svn_branching">Branching &amp; Merging</a></li>
1315
1316    <li>Code Management Working Practices &gt; <a href=
1317    "working_practices.html#branching">Branching &amp; Merging</a></li>
1318
1319    <li>FCM Command Reference &gt; <a href=
1320    "command_ref.html#fcm_svn_switch">fcm switch</a></li>
1321  </ul>
1322
1323  <h4>Switch a working copy to point to the trunk</h4>
1324
1325  <p>In the GUI, click on <span class="mono">&lt;Switch&gt;</span>. Enter
1326  "<tt>trunk</tt>" as the URL and then click on <span class=
1327  "mono">&lt;Run&gt;</span>.</p>
1328
1329  <p><em>Command line alternative</em>: use the <tt>fcm switch</tt> (or simply
1330  <tt>fcm sw</tt>) command. E.g.:</p>
1331  <pre>
1332(SHELL PROMPT)$ fcm sw trunk
1333</pre>
1334
1335  <p>To check that your working copy is pointing to the trunk, you should
1336  inspect the "corresponding URL" of your working copy while you are in the
1337  GUI.</p>
1338
1339  <p><em>Command line alternative</em>: use the <tt>fcm info</tt> command.</p>
1340
1341  <h4>Merge and commit your changes into the trunk</h4>
1342
1343  <p>In the GUI, click on <span class="mono">&lt;Merge&gt;</span>. Enter the
1344  name of your branch in the Source entry box, (e.g.
1345  "<tt>branches/test/frsn/r1_tutorial</tt>"). Click on <span class=
1346  "mono">&lt;Run&gt;</span> to proceed.</p>
1347
1348  <p><em>Command line alternative</em>: use the <tt>fcm merge</tt> command.
1349  E.g.</p>
1350  <pre>
1351(SHELL PROMPT)$ fcm merge branches/test/frsn/r1_tutorial
1352</pre>
1353
1354  <table class="pad" summary="merge back to trunk example" border="1" width=
1355  "100%">
1356    <tr>
1357      <th>Example output, merging changes back to the trunk</th>
1358    </tr>
1359
1360    <tr>
1361      <td>
1362        <pre>
1363Available Merges From /tutorial/branches/test/frsn/r1_tutorial: 7 6
1364About to merge in changes from /tutorial/branches/test/frsn/r1_tutorial@7
1365  compared with /tutorial/trunk@2
1366This merge will result in the following changes:
1367------------------------------------------------------------------------
1368D    doc/hello.html
1369A    doc/new_file.txt
1370U    src/module/hello_constants.f90
1371A    add.html
1372------------------------------------------------------------------------
1373Performing merge ...
1374D    doc/hello.html
1375A    doc/new_file.txt
1376U    src/module/hello_constants.f90
1377A    add.html
1378</pre>
1379      </td>
1380    </tr>
1381  </table>
1382
1383  <p>Since there is more than one revision available for merging, you will be
1384  prompted for the revision number you wish to merge from. The default is the
1385  last changed revision of your branch. which is the revision you want to merge
1386  with, so you should just proceed with the default.</p>
1387
1388  <p>Answer <span class="mono">&lt;Yes&gt;</span> when you are prompted to go
1389  ahead with the merge.</p>
1390
1391  <p>Since we merged in the latest changes from the trunk into the branch,
1392  there should be no conflicts from this merge.</p>
1393
1394  <p>Once again, please remember that the merge command only changes your
1395  working copy. You need to commit the change before it becomes permanent in
1396  the repository. Before you commit to the trunk, however, it is often sensible
1397  to have a last look at what you are going to change using the <tt>diff</tt>
1398  command.</p>
1399
1400  <p>Note: We have set up the repository to prevent any commits to the trunk to
1401  preserve the tutorial for other users, so your commit to the trunk will fail.
1402  However, you should try doing it any way to complete the exercise.</p>
1403
1404  <p>In the GUI, click on <span class="mono">&lt;Commit&gt;</span> and then on
1405  <span class="mono">&lt;Run&gt;</span>.</p>
1406
1407  <p><em>Command line alternative</em>: use the <tt>fcm commit</tt> (or simply
1408  <tt>fcm ci</tt>) command.</p>
1409
1410  <p>A text editor will appear to allow you to edit the commit message. You
1411  must add a commit message to describe your change <strong>above</strong> the
1412  line that says "<tt>--This line will be ignored and those below will be
1413  inserted automatically--</tt>". Since you are going to commit changes to the
1414  trunk, you should provide a useful message, including a link to your ticket.
1415  For example:</p>
1416
1417  <table summary="" border="1">
1418    <tr>
1419      <td>
1420        <pre>
1421For #2: complete the tutorial:
1422  1. Changed greeting in hello_constants.f90 to "Hello Earthlings!"
1423  2. Moved hello.html to add.html, and created a new document ''new_file.txt''
1424</pre>
1425      </td>
1426    </tr>
1427  </table>
1428
1429  <p>When you are ready, save your change and exit the editor.</p>
1430
1431  <p>As we have said before, the command will fail when you try to proceed with
1432  the commit.</p>
1433
1434  <h4>Close your ticket</h4>
1435
1436  <p>As you have completed your work, you should now update and close your
1437  ticket. In real life, you will typically include a closing comment with an
1438  appropriate Trac wiki link to the changeset in the trunk that fixes the
1439  ticket.</p>
1440
1441  <p>Since you cannot commit to the trunk in the tutorial, you can include a
1442  Trac link to the latest changeset in your branch. For example, you can put
1443  "<tt>Fixed at changeset [7].</tt>" in the comment. To mark the ticket as
1444  "fixed", move down to the <em>Action</em> box section, click on <span class=
1445  "mono">&lt;resolve as&gt;</span> and choose <em>fixed</em>. Use <span class=
1446  "mono">&lt;Preview&gt;</span> to ensure that your links work correctly. When
1447  you are happy, click on <span class="mono">&lt;Submit changes&gt;</span>.</p>
1448
1449  <h3><a name="tutorial_extra-extract">Extra activities on the extract and
1450  build systems</a></h3>
1451
1452  <p><em>The extract and build systems are very flexible. If you have time, you
1453  may want to explore their uses in more depth.</em></p>
1454
1455  <p>After completing this sub-section, you will learn how to:</p>
1456
1457  <ul>
1458    <li>extract from a working copy,</li>
1459
1460    <li>change a compiler flag, and</li>
1461
1462    <li>extract from a particular branch and/or revision from the
1463    repository.</li>
1464  </ul>
1465
1466  <p>Further reading:</p>
1467
1468  <ul>
1469    <li><a href="extract.html">The Extract System</a></li>
1470
1471    <li><a href="build.html">The Build System</a></li>
1472  </ul>
1473
1474  <h4>Extract from a working copy</h4>
1475
1476  <p>Modify the source files in your working copy and commit the changes back
1477  to your branch in the repository. Re-run <tt>"fcm extract"</tt> and <tt>"fcm
1478  build"</tt> and see the results of the changes. [The file(s) you have changed
1479  should be updated by "extract", and "build" should only re-build the
1480  necessary code.]</p>
1481
1482  <p>In fact, you can test changes in your working copy directly using a
1483  similar "extract" and "build" mechanism. In such case, you need to modify the
1484  REPOS declaration. For example:</p>
1485  <pre>
1486repos::tutorial::base  $HOME/fcm/work/r1_tutorial
1487</pre>
1488
1489  <h4>Change a compiler flag</h4>
1490
1491  <p>Modify the compiler flags, and re-run <tt>"fcm extract"</tt> and <tt>"fcm
1492  build"</tt> and see the results of the changes. To modify the compiler flags,
1493  edit your extract configuration file, and add the declarations for changing
1494  compiler flags. For example:</p>
1495  <pre>
1496# Declare extra options for Fortran compiler
1497bld::tool::fflags  -i8 -O3
1498</pre>
1499
1500  <p>For further information on how to set your compiler flags, please refer to
1501  the sub-section on <a href="build.html#basic_flags">Setting the compiler
1502  flags</a>.</p>
1503
1504  <h4>Extract from a particular branch and/or revision</h4>
1505
1506  <p>Try extracting from an earlier revision of your branch. Suppose the HEAD
1507  of your branch is revision 7, and the branch was created at an earlier
1508  revision. You can extract your branch at, say, revision 5 by adding a
1509  declaration in your extract configuration file:</p>
1510  <pre>
1511version::tutorial::base  5
1512</pre>
1513
1514  <p>You can also try extracting from the trunk. In such case, you will need to
1515  modify the REPOS declaration in your extract configuration file. For
1516  example:</p>
1517  <pre>
1518repos::tutorial::base  fcm:tutorial_tr/src
1519
1520# Extract with and without the following line and note the difference!
1521version::tutorial::base  1
1522</pre>
1523
1524  <h3><a name="tutorial_delete-branch">Delete your branch</a></h3>
1525
1526  <p><em>You should remove your branch when it is no longer required. When you
1527  remove it, it becomes invisible from the HEAD revision, but will continue to
1528  exist in the repository, should you want to refer to it in the
1529  future.</em></p>
1530
1531  <p>After completing this sub-section, you will learn how to:</p>
1532
1533  <ul>
1534    <li>list branches owned by you, and</li>
1535
1536    <li>delete a branch.</li>
1537  </ul>
1538
1539  <p>Further reading:</p>
1540
1541  <ul>
1542    <li>Code Management System &gt; Branching &amp; Merging &gt; <a href=
1543    "code_management.html#svn_branching_list">Listing Branches Created by You
1544    or Other Users</a></li>
1545
1546    <li>Code Management System &gt; Branching &amp; Merging &gt; <a href=
1547    "code_management.html#svn_branching_delete">Deleting Branches</a></li>
1548  </ul>
1549
1550  <h4>List branches owned by you</h4>
1551
1552  <p>If you forget what your branch is called and/or what other branches you
1553  have created, you can get a listing of all the branches you have created in a
1554  project. To do this in the GUI, click on <span class=
1555  "mono">&lt;Branch&gt;</span>, and then on the <span class=
1556  "mono">&lt;list&gt;</span> radio button. Click on <span class=
1557  "mono">&lt;Run&gt;</span>.</p>
1558
1559  <p><em>Command line alternative</em>: use the <tt>fcm branch --list</tt> (or
1560  simply <tt>fcm br -l</tt>) command.</p>
1561
1562  <h4>Delete a branch</h4>
1563
1564  <p>Switch your working copy to point back to your branch. In the GUI, click
1565  on <span class="mono">&lt;Switch&gt;</span>. Enter the name of your branch as
1566  the URL and click on <span class="mono">&lt;Run&gt;</span> to proceed.</p>
1567
1568  <p><em>Command line alternative</em>: use the <tt>fcm switch
1569  &lt;URL&gt;</tt> (or simply <tt>fcm sw &lt;URL&gt;</tt>) command.</p>
1570
1571  <p>You can continue your work in the branch if you wish, but once you have
1572  finished all the work, you should delete it. To do so in the GUI, click on
1573  <span class="mono">&lt;Branch&gt;</span> in the GUI. Check the <span class=
1574  "mono">&lt;delete&gt;</span> radio button, and click <span class=
1575  "mono">&lt;Run&gt;</span> to proceed.</p>
1576
1577  <p><em>Command line alternative</em>: use the <tt>fcm branch --delete</tt> (or
1578  simply <tt>fcm br -d</tt>) command.</p>
1579
1580  <table class="pad" summary="branch delete example" border="1" width="100%">
1581    <tr>
1582      <th>Example output, deleting a branch</th>
1583    </tr>
1584
1585    <tr>
1586      <td>
1587        <pre>
1588URL: svn://fcm1/tutorial_svn/tutorial/branches/test/frsn/r1_tutorial
1589Repository Root: svn://fcm1/tutorial_svn
1590Repository UUID: cb858ce8-0f05-0410-9e64-efa98b760b62
1591Revision: 7
1592Node Kind: directory
1593Last Changed Author:
1594Last Changed Rev: 7
1595Last Changed Date: 2005-11-09 09:11:57 +0000 (Wed, 09 Nov 2005)
1596--------------------------------------------------------------------------------
1597Branch Create Rev: 5
1598Branch Create Date: 2005-11-09 08:34:22 +0000 (Wed, 09 Nov 2005)
1599Branch Parent: svn://fcm1/tutorial_svn/tutorial/trunk@1
1600--------------------------------------------------------------------------------
1601Last Merge From Trunk: /tutorial/branches/test/frsn/r1_tutorial@7
1602                       /tutorial/trunk@2
1603Avail Merges Into Trunk: 7 6
1604Starting nedit to create commit message ...
1605Commit message is as follows:
1606------------------------------------------------------------------------
1607Deleted tutorial/branches/test/frsn/r1_tutorial.
1608--This line, and those below, will be ignored--
1609D    svn://fcm1/tutorial_svn/tutorial/branches/test/frsn/r1_tutorial
1610------------------------------------------------------------------------
1611Deleting branch
1612  svn://fcm1/tutorial_svn/tutorial/branches/test/frsn/r1_tutorial ...
1613
1614Committed revision 8.
1615</pre>
1616      </td>
1617    </tr>
1618  </table>
1619
1620  <p>You will be prompted to edit the commit message file. A standard template
1621  is automatically supplied for the commit. However, if you want to add extra
1622  comment for the branch, please do so <strong>above</strong> the line that
1623  says "<tt>--This line will be ignored and those below will be inserted
1624  automatically--</tt>". Save your change and exit the editor.</p>
1625
1626  <p>Answer <span class="mono">&lt;Yes&gt;</span> when you are prompted to go
1627  ahead and delete this branch.</p>
1628
1629  <p>Your working copy is now pointing to a branch that no longer exists at the
1630  HEAD revision of the repository. If you want to try the tutorial again, you
1631  may want to create another branch, and switch your working copy to point to
1632  the new branch. Otherwise, you can remove your working copy by issuing a
1633  careful <tt>rm -rf</tt> command.</p>
1634
1635  <h3><a name="tutorial_delete-final-comments">Final comments</a></h3>
1636
1637  <p>We have guided you through the basics of the complete change process,
1638  using recommended ways of working. Most of the basic and important commands
1639  have been covered by the tutorial. (The only exception is <tt>update</tt>,
1640  which you may have to use regularly. For information on the command, please
1641  refer to the section on <a href=
1642  "http://svnbook.red-bean.com/en/1.2/svn.tour.cycle.html#svn.tour.cycle.update">
1643  Update Your Working Copy</a> in the <a href=
1644  "http://svnbook.red-bean.com/en/1.2/">Subversion book</a>.) You should now be
1645  in a position to continue with your development work with FCM. However, if at
1646  any time you are unsure about any aspect of using FCM, please consult the
1647  relevant section of the <a href="index.html">FCM User Guide</a>.</p>
1648
1649  <p>Feel free to use the tutorial, at any time, for testing out any aspect of
1650  the system. You may wish to do this rather than use your own repository and
1651  ticket system, to avoid cluttering them with unwanted junk.</p>
1652 
1653  <script type="text/javascript" src="maintain.js">
1654  </script>
1655</body>
1656</html>
Note: See TracBrowser for help on using the repository browser.