source: LMDZ5/trunk/tools/fcm/doc/user_guide/working_practices.html @ 5184

Last change on this file since 5184 was 1578, checked in by jghattas, 13 years ago
  • Add fcm in LMDZ5/tools directory

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