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

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

source: vendors/fcm/current/doc/user_guide/getting_started.html @ 1980

Last change on this file since 1980 was 1980, checked in by flavoni, 14 years ago

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