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/fcm/current/doc/user_guide – NEMO

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

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

importing fcm vendor

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