Context Navigation

working_practices.html

Last change on this file 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> > 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 diff --branch <branch_name></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 & 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
430	Conflicts in file: document.doc
431	document.doc: ignoring binary file, please resolve conflicts manually.
432	(SHELL PROMPT)$ fcm status
433	=> svn st
434	? document.doc.r100
435	? document.doc.r101
436	C 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 > 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	=> svn resolved document.doc
459	Resolved conflicted state of 'document.doc'
460	(SHELL PROMPT)$ fcm status
461	=> svn st
462	M 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>
527	No 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 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 log -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.

Context Navigation

source: LMDZ5/branches/IPSLCM6.0.11/tools/fcm/doc/user_guide/working_practices.html

Download in other formats: