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.
working_practices.html in vendors/doc/user_guide – NEMO

source: vendors/doc/user_guide/working_practices.html @ 10669

Last change on this file since 10669 was 10669, checked in by nicolasmartin, 5 years ago

Import latest FCM release from Github into the repository for testing
File size: 31.8 KB
Line 
1<!DOCTYPE html>
2<html>
3<head>
4  <title>FCM: User Guide: Code Management Working Practices</title>
5  <meta name="author" content="FCM team" />
6  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7  <link rel="icon" href="../etc/fcm-icon.png" type="image/png" />
8  <link rel="shortcut icon" href="../etc/fcm-icon.png" type="image/png" />
9  <link href="../etc/bootstrap/css/bootstrap.min.css" rel="stylesheet" media="screen" />
10  <link href="../etc/fcm.css" rel="stylesheet" media="screen" />
11</head>
12<body>
13  <div class="navbar navbar-inverse">
14    <div class="container-fluid">
15      <div class="navbar-header">
16        <a class="navbar-brand" href=".."><span class="fcm-version">FCM</span></a>
17      </div>
18      <div class="collapse navbar-collapse">
19        <ul class="nav navbar-nav">
20          <li><a href="../installation/">Installation</a></li>
21
22          <li><a class="active" href="#">User Guide</a></li>
23        </ul>
24      </div>
25    </div>
26  </div>
27
28  <div class="page-header">
29    <div class="fcm-page-content pull-right well well-sm"></div>
30    <h1>FCM: User Guide: Code Management Working Practices</h1>
31  </div>
32
33  <div class="container">
34  <div class="row">
35  <div class="col-md-12">
36
37  <h2 id="introduction">Introduction</h2>
38
39  <p>The previous chapter described how to use the various parts of the FCM
40  code management system. They also described aspects of working practices
41  which are enforced by the system. This section discusses other recommended
42  working practices. They are optional in the sense that you don't have to
43  follow them to use FCM. It is a matter for individual projects to decide
44  which working practices to adopt (although we expect most projects/systems
45  using FCM to adopt similar practices).</p>
46
47  <h2 id="changes">Making Changes</h2>
48
49  <p>This sub-section gives an overview of the recommended approach for
50  preparing changes. Particular topics are discussed in more detail in later
51  sub-sections where appropriate.</p>
52
53  <p>The recommended process for making a change is as follows:</p>
54
55  <ol>
56    <li>Before work starts on any coding you should make sure that there is a
57    Trac ticket open which explains the purpose of the change.
58
59      <ul>
60        <li>Make sure that you set the ticket milestone to indicate which
61        release of the system you are aiming to include your change in.</li>
62
63        <li>Accept the ticket to indicate that you are working on the
64        change.</li>
65
66        <li>For further advice on using tickets see <a href="#tickets">Trac
67        Tickets</a> later in this section.</li>
68      </ul>
69    </li>
70
71    <li>Create a branch
72
73      <ul>
74        <li>For very simple changes you may be happy to prepare your changes
75        directly on the trunk. For further details see <a href=
76        "#branching_when">When to Branch</a> later in this section.</li>
77
78        <li>Create your branch either from the latest revision or from a stable
79        release (see <a href="#branching_where">Where to Branch From</a> later
80        in this section).</li>
81      </ul>
82    </li>
83
84    <li>Prepare your code changes on the branch
85
86      <ul>
87        <li>Commit interim versions to your branch on a regular basis as you
88        develop your change. This makes it much easier to keep track of what
89        you're changing and to revert changes if necessary.</li>
90
91        <li>You may wish to merge in changes from the trunk. For further
92        details see <a href="#branching_update">Merging From the Trunk</a>
93        later in this section.
94
95          <ul>
96            <li>Make sure that you always commit any local changes to your
97            branch before doing a merge. Otherwise it becomes impossible to
98            distinguish your changes from those you have merged in. It is also
99            impossible to revert the merge without losing your local
100            changes.</li>
101
102            <li>Likewise, always commit the merge to your branch (after
103            resolving any conflicts) before making any further changes.</li>
104          </ul>
105        </li>
106
107        <li>Don't include unrelated changes. If you want to make some changes
108        which aren't really associated with your other changes then use a
109        separate ticket and branch for these changes.</li>
110      </ul>
111    </li>
112
113    <li>Once your changes are ready for review, update the Trac ticket to
114    record which revision of the branch is to be reviewed and assign the ticket
115    to your reviewer.</li>
116
117    <li>If the reviewer is happy with the change then he/she should update the
118    ticket to record that the change is approved and assign the ticket back to
119    you.
120
121      <ul>
122        <li>The reviewer can use the command <code>fcm&nbsp;branch-diff
123        &lt;branch_name&gt;</code> to examine all of the changes on the
124        branch.</li>
125
126        <li>If changes are necessary then these should be prepared and then the
127        ticket updated to refer to the new revision under review.</li>
128      </ul>
129    </li>
130
131    <li>Once the change is approved it can be merged back to the trunk
132
133      <ul>
134        <li>If you have been merging the latest changes from the trunk onto
135        your branch then the merge should be automatic. If not you may have
136        conflicts to resolve.</li>
137
138        <li>Make sure that each merge is a separate commit to the trunk. i.e.
139        Don't combine changes from several branches in one commit. This makes
140        it easier to reverse changes if necessary. It also makes the changeset
141        easier to understand.</li>
142
143        <li>Make sure that you use a good log message to describe your change.
144        For further details see <a href="#messages">Commit Log Messages</a>
145        later in this section.</li>
146
147        <li>Once the changes are commited, update the ticket to refer to the
148        changeset. Then the ticket can be closed.</li>
149      </ul>
150    </li>
151
152    <li>Once you are finished with the branch it should be deleted.</li>
153  </ol>
154
155  <h2 id="wc">Working Copies</h2>
156
157  <p>Some points to consider regarding working copies:</p>
158
159  <ol>
160    <li>If the size of your project is small then you will probably find it
161    easiest to work with a complete copy of the project (either the trunk or
162    your branch). This means that you always have immediate access to all the
163    files and that you are always able to perform merges using your normal
164    working copy.</li>
165
166    <li>If you have a large project then you may prefer to work on a sub-tree
167    of your project.
168
169      <p><dfn>Pros:</dfn></p>
170
171      <ul>
172        <li>Subversion operations on your working copy are faster.</li>
173
174        <li>Your working copies use up less disk space. Remember that you may
175        be working on several changes at once on separate branches so you may
176        wish to have several working copies.</li>
177      </ul>
178
179      <p><dfn>Cons:</dfn></p>
180
181      <ul>
182        <li>You cannot always perform merge operations in sub-trees (if the
183        changes which need to be merged include files outside of your
184        sub-tree). To handle this we suggest that if you need to perform a
185        merge using a complete copy of your project you check it out in your
186        <var>$LOCALDATA</var> area (local disk space which is not backed up) to
187        be used purely for doing the merge.</li>
188
189        <li>You may find that your change involves more files than you
190        originally thought and that some of the files to be changed lie outside
191        of your working copy. You then have to make sure that you have
192        committed any changes before checking out a larger working copy.</li>
193      </ul>
194    </li>
195  </ol>
196
197  <h2 id="branching">Branching &amp; Merging</h2>
198
199  <h3 id="branching_when">When to Branch</h3>
200
201  <p>If you are making a reasonably large change which will take more than a
202  hour or two to prepare then there are clear advantages to doing this work on
203  a branch.</p>
204
205  <ul>
206    <li>You can commit intermediate versions to the branch.</li>
207
208    <li>If you need to merge in changes from the trunk then you have a record
209    of your files prior to the merge.</li>
210
211    <li>The version of the code which gets reviewed is recorded. If subsequent
212    changes are required then only those changes will need reviewing.</li>
213  </ul>
214
215  <p>However, if you are only making a small change (maybe only one line)
216  should you create a branch for this? There are two possible approaches:</p>
217
218  <dl>
219    <dt>Always Branch</dt>
220
221    <dd>
222      <p>ALL coding changes are prepared on branches.</p>
223
224      <p><dfn>Pros:</dfn> Same process is followed in all cases.</p>
225
226      <p><dfn>Cons:</dfn> The extra work required to create the branch and
227      merge it back to the trunk may seem unnecessary for a very small
228      change.</p>
229    </dd>
230
231    <dt>Branch When Needed</dt>
232
233    <dd>
234      <p>Small changes can be committed directly to the trunk (after testing
235      and code review).</p>
236
237      <p><dfn>Pros:</dfn> Avoids the overhead of using branches.</p>
238
239      <p><dfn>Cons:</dfn> Danger of underestimating the size of a change. What
240      you thought was a small change may turn out to be larger than you thought
241      (although you can always move it onto a branch if this happens).</p>
242    </dd>
243  </dl>
244
245  <p>This is a matter for project policy although, in general, we would
246  recommend the <cite>Branch When Needed</cite> approach.</p>
247
248  <h3 id="branching_where">Where to Branch From</h3>
249
250  <p>When you create a new branch you have two choices for which revision to
251  create the branch from:</p>
252
253  <dl>
254    <dt>The latest revision of the trunk</dt>
255
256    <dd>
257      <p>This is the preferred choice where possible. It minimised the chances
258      of conflicts when you need to incorporate your changes back onto the
259      trunk.</p>
260    </dd>
261
262    <dt>An older revision of the trunk</dt>
263
264    <dd>
265      <p>There are a number of reasons why you may need to do this. For
266      example:</p>
267
268      <ul>
269        <li>You are using a stable version to act as your <em>control</em>
270        data.</li>
271
272        <li>You need to know that your baseline is well tested (e.g. scientific
273        changes).</li>
274
275        <li>Your change may need to be merged with other changes relative to a
276        stable version for testing purposes or for use in a package (see
277        <a href="#packages">Creating Packages</a> later in this section).</li>
278      </ul>
279    </dd>
280  </dl>
281
282  <h3 id="branching_update">Merging From the Trunk</h3>
283
284  <p>Once you've created your branch you need to decide whether you now work in
285  isolation or whether you periodically merge in the latest changes from the
286  trunk.</p>
287
288  <ul>
289    <li>Regularly merging from the trunk minimises the work involved when you
290    are ready to merge back to the trunk. You deal with any merge issues as you
291    go along rather than all at the end (by which time your branch and the
292    trunk could have diverged significantly).</li>
293
294    <li>One downside of merging from the trunk is that the baseline for your
295    changes is a moving target. This may not be what you want if you have some
296    <em>control</em> results that you have generated.</li>
297
298    <li>Another downside of merging from the trunk is that it may introduce
299    bugs. Although any code on the trunk should have been tested and reviewed
300    it is unlikely to be as well tested as code from a stable release.</li>
301
302    <li>Unless you originally created your branch from the latest revision of
303    the trunk it is unlikely that you are going to want to merge in changes
304    from the trunk. The exception to this is once your change is complete when
305    it may make sense to merge all the changes on the trunk into your branch as
306    a final step. This is discussed in <a href="#branching_commit">Merging Back
307    to the Trunk</a> below.</li>
308  </ul>
309
310  <p>So, there are basically three methods of working:</p>
311
312  <dl>
313    <dt>Branch from a stable version and prepare all your changes in
314    isolation</dt>
315
316    <dd>Necessary if you need to make your change relative to a well tested
317    release.</dd>
318
319    <dt>Branch from the latest code but then prepare all your changes in
320    isolation</dt>
321
322    <dd>Necessary if you need a stable baseline for your <em>control</em>
323    data.</dd>
324
325    <dt>Branch from the latest code and then update your branch from the trunk
326    on a regular basis</dt>
327
328    <dd>This is considered <em>best practice</em> for parallel working and
329    should be used where possible.</dd>
330  </dl>
331
332  <h3 id="branching_commit">Merging Back to the Trunk</h3>
333
334  <p>Before merging your change back to the trunk you will need to test your
335  change and get it reviewed. There are two options for what code to test and
336  review:</p>
337
338  <dl>
339    <dt>Test and review your changes in isolation, then merge to the trunk and
340    deal with any conflicts</dt>
341
342    <dd>
343      <p>This may be the best method if:</p>
344
345      <ul>
346        <li>Your changes have already been tested against a stable baseline and
347        re-testing after merging would be impracticable.</li>
348
349        <li>Your branch needs to be available for others to merge in its
350        changes in isolation.</li>
351      </ul>
352    </dd>
353
354    <dt>Merge in the latest code from the trunk before your final test and
355    review</dt>
356
357    <dd>
358      <p>This has the advantage that you are testing and reviewing the actual
359      code which will be committed to the trunk. However, it is possible that
360      other changes could get committed to the trunk whilst you are completing
361      your testing and review. There are several ways of dealing with this:</p>
362
363      <ul>
364        <li>Use locking to prevent it happening. The danger with this is that
365        you may prevent others from being able to get their change tested and
366        reviewed, hence inhibiting parallel devlopment.</li>
367
368        <li>Insist that the change is re-tested and reviewed. The problem with
369        this is that there is no guarantee that the same thing won't happen
370        again.</li>
371
372        <li>Merge in the new changes but don't insist on further testing or
373        review.
374
375          <ul>
376            <li>In most cases any changes won't clash so there is little to
377            worry about.</li>
378
379            <li>Where there are clashes then, in most cases, they will be
380            trivial with little danger of any side-effects.</li>
381
382            <li>Where the clashes are significant then, in most cases, this
383            will be very obvious whilst you are resolving the conflicts. In
384            this case you should repeat the testing and get the updates
385            reviewed.</li>
386          </ul>This is the recommended approach since it doesn't inhibit
387          parallel development and yet the chances of a bad change being
388          committed to the trunk are still very small.
389        </li>
390      </ul>
391
392      <p>You should also consider what can be done to minimise the time taken
393      for testing and review.</p>
394
395      <ul>
396        <li>Try to keep your changes small by breaking them down where
397        possible. Smaller changes are easier and quicker to review. This also
398        helps to minimise merge problems by getting changes back onto the trunk
399        earlier.</li>
400
401        <li>Automate your testing as far as possible to speed up the
402        process.</li>
403      </ul>
404    </dd>
405  </dl>
406
407  <p>Most projects will require the developer who prepared the change to merge
408  it back to the trunk once it is complete. However, larger projects may wish
409  to consider restricting this to a number of experienced / trusted
410  developers.</p>
411
412  <ul>
413    <li>This makes it easier to control and prioritise the merges.</li>
414
415    <li>It applies an extra level of quality control.</li>
416
417    <li>It minimises the risk of mistakes being merged back on to the trunk by
418    less experienced developers</li>
419
420    <li>Scientific developers can concentrate on the scientific work.</li>
421
422    <li>One issue is that the person doing the merge to the trunk may need help
423    from the original developer to prepare a suitable log message.</li>
424  </ul>
425
426  <h3 id="branching_delete">When to Delete Branches</h3>
427
428  <p>Once you are finished with your branch it is best to delete it to avoid
429  cluttering up the directory tree (remember that the branch and all its
430  history will still be available). There are two obvious approaches to
431  deleting branches:</p>
432
433  <dl>
434    <dt>Delete the branch as soon as it has been merged back to the trunk
435    (prior to closing any associated Trac ticket)</dt>
436
437    <dd>This is the tidiest approach which minimises the chances of old
438    branches being left around.</dd>
439
440    <dt>Delete the branch once a stable version of the system has been released
441    which incorporates your change</dt>
442
443    <dd>If a bug is found in your change during integration testing then you
444    can prepare the fix on the original branch (without having to do any
445    additional work to restore the branch).</dd>
446  </dl>
447
448  <h2 id="binary">Working with Binary Files</h2>
449
450  <p>The <code>fcm conflicts</code> command and <code>xxdiff</code> can only
451  help you resolve conflicts in text files. If you have binary files in your
452  repository you need to consider whether conflicts in these files would cause
453  a problem.</p>
454
455  <h3 id="binary_conflicts">Resolving Conflicts in Binary Files</h3>
456
457  <p>Conflicts in some types of binary files can be resolved manually. When you
458  are satisfied that the conflicts are resolved, issue the <code>fcm
459  resolved</code> command on the file to remove the conflict status. (You will
460  be prevented from committing if you have a conflicting file in your working
461  copy.)</p>
462
463  <p>If you have a conflicting MS Office 2003+ document, you may be able to
464  take advantage of the <kbd>Tools &gt; Compare and Merge Documents</kbd>
465  facility. Consider a working copy, which you have just updated from revision
466  100 to revision 101, and someone else has committed some changes to a file
467  <samp>doument.doc</samp> you are editing, you will get:</p>
468  <pre>
469(SHELL PROMPT)$ fcm conflicts
470Conflicts in file: document.doc
471document.doc: ignoring binary file, please resolve conflicts manually.
472(SHELL PROMPT)$ fcm status
473=&gt; svn st
474?      document.doc.r100
475?      document.doc.r101
476C      document.doc
477</pre>
478
479  <p>Open <samp>document.doc.r101</samp> with MS Word. In <kbd>Tools &gt;
480  Compare and Merge Documents...</kbd>, open <samp>document.doc</samp>. You
481  will be in Track Changes mode automatically. Go through the document to
482  accept, reject or merge any changes. Save the document and exit MS Word when
483  you are ready. Finally, issue the <code>fcm resolved</code> command to remove
484  the conflict status:</p>
485  <pre>
486(SHELL PROMPT)$ fcm resolved document.doc
487=&gt; svn resolved document.doc
488Resolved conflicted state of 'document.doc'
489(SHELL PROMPT)$ fcm status
490=&gt; svn st
491M      document.doc
492</pre>
493
494  <p>Another type of conflict that you may be able to resolve manually is where
495  the binary file is generated from another file which can be merged. For
496  instance, some people who use LaTeX also store a PDF version of the document
497  in the repository. In such cases it is easy to resolve the conflict by
498  re-generating the PDF file from the merged LaTeX file and then issuing the
499  <code>fcm resolved</code> command to remove the conflict status. Note that,
500  in this particular case, a better approach might be to automate the
501  generation of the PDF file outside of the repository.</p>
502
503  <h3 id="binary_locking">Using Locking</h3>
504
505  <p>For files with binary formats, such as artwork or sound, it is often
506  impossible to merge conflicting changes. In these situations, it is necessary
507  for users to take strict turns when changing the file in order to prevent
508  time wasted on changes that are ultimately discarded.</p>
509
510  <p>Subversion supports <q title=
511  "http://svnbook.red-bean.com/en/1.8/svn.advanced.locking.html">locking</q> to
512  allow you to prevent other users from modifying a file while you are
513  preparing changes. For details please refer to the chapter <a href=
514  "http://svnbook.red-bean.com/en/1.8/svn.advanced.locking.html">Locking</a>
515  from the Subversion book. Note that:</p>
516
517  <ul>
518    <li>FCM does not add any functionality to the locking commands provided by
519    Subversion.</li>
520
521    <li>If you need to lock a file you must do this in a working copy of the
522    trunk. There is nothing to stop you preparing the changes in a branch
523    (maybe you want to prepare the change in combination with a number of other
524    changes which do not require locking). However, you must always remember to
525    lock the file in the trunk first to prevent other users from preparing
526    changes to the file in parallel.</li>
527
528    <li>Locking isn't the only way of preventing conflicts with binary files.
529    If you only have a small project team and a small number of binary files
530    you may find it easier to use other methods of communication such as emails
531    or just talking to each other. Alternatively, you may have a working
532    practice that particular files are only modified by particular users.</li>
533  </ul>
534
535  <h2 id="messages">Commit Log Messages</h2>
536
537  <p>Certain guidelines should be adhered to when writing log messages for code
538  changes when committing to the trunk:</p>
539
540  <ul>
541    <li>Start with a link to the ticket that raises the issues you are
542    addressing.</li>
543
544    <li>Add a keyword to indicate the command/module affected by this change.</li>
545
546    <li>Add a summary of the change.</li>
547
548    <li>Use Trac wiki syntax that can be displayed nicely in plain text.</li>
549
550    <li>E.g. <samp>#429: user guide: improve commit log guidelines.</samp></li>
551  </ul>
552
553  <p>If you realise that you have made a mistake in the commit log, you can
554  modify it by using the command <code>fcm propedit svn:log --revprop -r REV
555  TARGET</code>. Take care since this is an <a href=
556  "http://svnbook.red-bean.com/en/1.8/svn.advanced.props.html">unversioned</a>
557  property so you run the risk of losing information if you aren't careful with
558  your edits.</p>
559
560  <p>There are two possible approaches to recording the changes to individual
561  files:</p>
562
563  <dl>
564    <dt>Maintain history entries in file headers</dt>
565
566    <dd>
567      <p><dfn>Pros:</dfn> You don't need access to the Subversion repository in
568      order to be able to view a files change history (e.g. external
569      collaborators).</p>
570
571      <p><dfn>Cons:</dfn></p>
572
573      <ul>
574        <li>History entries will produce clashes whenever files are changed in
575        parallel (although these conflicts are trivial to resolve).</li>
576
577        <li>Source files which are changed regularly can become cluttered with
578        very long history entries.</li>
579
580        <li>It is not possible to include history entries in some types of
581        file.</li>
582      </ul>
583    </dd>
584
585    <dt>Record which files have changed in the commit log message</dt>
586
587    <dd>
588      <p>The log message should name every modified file and explain why it was
589      changed. Make sure that the log message includes some sort of description
590      for every change. The value of the log becomes much less if developers
591      cannot rely on its completeness. Even if you've only changed comments,
592      note this in the message. For example:</p>
593      <pre>
594 * working_practices.html:
595   Added guidelines for writing log messages.
596</pre>
597
598      <p>If you make exactly the same change in several files, list all the
599      changed files in one entry. For example:</p>
600      <pre>
601 * code_management.html, system_admin.html, index.html:
602   Ran pages through tidy to fix HTML errors.
603</pre>
604
605      <p>It shouldn't normally be necessary to include the full path in the
606      file name - just make sure it is clear which of the changed files you are
607      referring to. You can get a full list of the files changed using
608      <code>fcm log -v</code>.</p>
609    </dd>
610  </dl>
611
612  <p>When you're committing to your own branch then you can be much more
613  relaxed about log messages. Use whatever level of detail you find helpful.
614  However, if you follow similar guidelines then this will help when it comes
615  to preparing the log message when your change is merged back to the
616  trunk.</p>
617
618  <h2 id="tickets">Trac Tickets</h2>
619
620  <h3 id="tickets_create">Creating Tickets</h3>
621
622  <p>There are two different approaches to using the issue tracker within
623  Trac:</p>
624
625  <dl>
626    <dt>All problems should be reported using Trac tickets</dt>
627
628    <dd>
629      <p><dfn>Pros:</dfn> The issue tracker contains a full record of all the
630      problems reported and enhancements requested.</p>
631
632      <p><dfn>Cons:</dfn> The issue tracker gets cluttered up with lots of
633      inappropriate tickets, (which can make it much harder to search the
634      issues and can slow down the response to simple issues).</p>
635
636      <ul>
637        <li>Duplicate tickets.</li>
638
639        <li>Issues already discussed in the documentation.</li>
640
641        <li>Problems which turn out to be unrelated to the system.</li>
642
643        <li>Problems which are poorly described.</li>
644
645        <li>Things which would be better solved by a quick conversation.</li>
646      </ul>
647    </dd>
648
649    <dt>A Trac ticket shouldn't be created until the issue has been agreed</dt>
650
651    <dd>
652      <p>Problems and issues should first be discussed with the project team /
653      system maintainers. Depending on the project, this could be via email, on
654      the newsgroups or through a quick chat over coffee.</p>
655
656      <p>Nothing is lost this way. Issues which are appropriate for the issue
657      tracker still get filed. It just happens slightly later, after initial
658      discussion has helped to clarify the best description for the issue.</p>
659    </dd>
660  </dl>
661
662  <h3 id="tickets_use">Using Tickets</h3>
663
664  <p>This sub-section provides advice on the best way of using tickets:</p>
665
666  <ol>
667    <li>In general, mature systems will require that there is a Trac ticket
668    related to every changeset made to the trunk. However this doesn't mean
669    that there should be a separate ticket for each change.
670
671      <ul>
672        <li>If a change is made to the trunk and then a bug is subsequently
673        found then, if this happens before the next release of the system, the
674        subsequent change can be recorded on the same ticket.</li>
675
676        <li>There can often be changes which don't really affect the system
677        itself since they are just system administration details. One way of
678        dealing with this is to open a ticket for each release in which to
679        record all such miscellaneous changes. It will probably be acceptable
680        to review these changes after they have been committed, prior to the
681        system release.</li>
682      </ul>
683    </li>
684
685    <li>Whenever you refer to source files/directories in tickets, make sure
686    that you refer to particular revisions of the files. This ensures that the
687    links will work in the future, even if those files are no longer in the
688    latest revision. For example:<br />
689    <samp>Changes now ready for review:
690    source:/OPS/branches/dev/frdm/r123_MyBranch@234</samp></li>
691
692    <li>For some types of information, simply appending to the ticket may not
693    be the best way of working. For example, design notes or test results may
694    be best recorded elsewhere, preferably in a wiki page. If using wiki pages
695    we recommend using a naming convention to identify the wiki page with the
696    associated ticket, for example:<br />
697    <samp>Please refer to [wiki:ticket/123/Design design notes]</samp><br />
698    <samp>See separate [wiki:ticket/123/TestResults test results]</samp><br />
699    Note that the square brackets have to be used since a page name containing
700    numbers is not recognised automatically.</li>
701  </ol>
702
703  <h2 id="packages">Creating Packages</h2>
704
705  <p>Sometimes you may need to combine the changes from several different
706  branches. For example:</p>
707
708  <ul>
709    <li>Your branch is just part of a larger change which needs to be tested in
710    its entirety before committing to the trunk.</li>
711
712    <li>You have some diagnostic code stored on a branch which you want to
713    combine with another branch for testing purposes.</li>
714  </ul>
715
716  <p>We refer to this as creating a <em>package</em>.</p>
717
718  <p>To create a package you simply create a new branch as normal. The
719  <em>type</em> should be a <em>package</em> or possibly a
720  <em>configuration</em> branch to help you distinguish it from your other
721  branches. You then simply merge in all of the branches that you want to
722  combine using <code>fcm merge</code>.</p>
723
724  <ul>
725    <li>The chance of conflicts will be reduced if the branches you are
726    combining have been created from the same point on the trunk. Your package
727    branch should also be created from the same point on the trunk.
728
729      <ul>
730        <li><em>Currently, <code>fcm merge</code> will not work unless this is
731        true.</em></li>
732      </ul>
733    </li>
734
735    <li>If further changes are made on a branch you are using in a package then
736    you can incorporate these changes into your package using <code>fcm
737    merge</code>. Note, however, that if you have a branch which is being used
738    in a package then you should avoid merging changes from the trunk into your
739    branch. If you do then it will be very difficult to get updates to your
740    branch merged into the package.</li>
741  </ul>
742
743  <p>The <code>fcm branch-info</code> command is very useful for maintaining
744  packages. It tells you all of the branches which have been merged into your
745  package and whether there are any more recent changes on those branches.</p>
746
747  <h2 id="releases">Preparing System Releases</h2>
748
749  <p>There are two ways of preparing system releases:</p>
750
751  <dl>
752    <dt>A system release is simply a particular revision of the trunk</dt>
753
754    <dd>
755      <p>In order to do this it will be necessary to restrict changes on the
756      trunk whilst the release is being prepared.</p>
757
758      <ul>
759        <li>Users can continue to develop changes not intended for inclusion in
760        this release on branches.</li>
761
762        <li>This may be a problem if preparing the release takes too long.</li>
763      </ul>
764    </dd>
765
766    <dt>Create a release branch where the release is finalised</dt>
767
768    <dd>
769      <p>You then lose the ability to be able to branch from the release.</p>
770
771      <p>It may be harder to identify what changes have been made between
772      releases (since you can't simply look at all the changesets made between
773      two revisions of the trunk).</p>
774    </dd>
775  </dl>
776
777  <h2 id="rapid">Rapid vs Staged Development Practices</h2>
778
779  <p>Most of this section on working practices has focussed on projects/systems
780  which are quite mature. Such systems are likely to have regular releases and
781  will, for example, insist that all changes to the trunk are reviewed and
782  tested.</p>
783
784  <p>If your system is still undergoing rapid development and has not yet
785  reached any sort of formal release then you will probably want to adopt a
786  much more relaxed set of working practices. For example:</p>
787
788  <ul>
789    <li>Changes don't need to be reviewed.</li>
790
791    <li>More changes will be committed to the trunk. Only very large changes
792    will be prepared on branches.</li>
793
794    <li>No requirement to have a Trac ticket associated with each change.</li>
795  </ul>
796
797  <p>We have tried to avoid building too many assumptions about working
798  practices into the FCM system. This gives projects the flexibility to decide
799  which working practices are appropriate for their system. Hopefully this
800  means that FCM can be used for large or small systems and for rapidly
801  evolving or very stable systems.</p>
802
803  </div>
804  </div>
805  </div>
806
807  <hr/>
808  <div class="container-fluid text-center">
809    <div class="row"><div class="col-md-12">
810    <address><small>
811      &copy; British Crown Copyright 2006-16
812      <a href="http://www.metoffice.gov.uk">Met Office</a>.
813      See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
814      This document is released under the British <a href=
815      "http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
816      "license">Open Government Licence</a>.<br />
817    </small></address>
818    </div></div>
819  </div>
820
821  <script type="text/javascript" src="../etc/jquery.min.js"></script>
822  <script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
823  <script type="text/javascript" src="../etc/fcm.js"></script>
824  <script type="text/javascript" src="../etc/fcm-version.js"></script>
825</body>
826</html>
Note: See TracBrowser for help on using the repository browser.