[m-rev.] for review: upgrade boehm_gc documentation

[Peter Ross]

On Wed, May 07, 2003 at 11:01:52PM +1000, Fergus Henderson wrote:
> On 07-May-2003, Peter Ross <pro at missioncriticalit.com> wrote:
> > compiler/notes/upgrade_boehm_gc.html:
> > 	Description of how to upgrade the boehm gc to a new version.
> ...
> > +<P>
> > +Import the new source on to the vendor branch.
> > +Note that gc_6_2alpha4 should be a tag which corresponds to
> > +the version of the collector that you are importing.
> > +<PRE>
> > +# cvs import -I \! mercury/boehm_gc gc gc_6_2alpha4
> > +</PRE>
> > +</P>
> 
> There should be a big warning here.
> 
> > +<P>
> > +Unfortunately the last step can leave the repository in an inconsistent state.
> > +What happens is that some files have never been modified by the Mercury team,
> > +but they have been modified by various upgrades to the collector.
> > +These files live on the vendor branch.
> > +For example, before upgrading the collector the file, BCC_MAKEFILE,
> > +had the version number, 1.1.1.6.
> > +However if the upgrade of the collector has requires a modification to
> > +BCC_MAKEFILE then the new version will be 1.1.1.7 on the vendor branch
> > +and when you update boehm_gc you will get version 1.1.1.7 of BCC_MAKEFILE,
> > +which is obviously inconsistent.
> > +</P>
> > +
> > +<P>
> > +How to fix this problem.
> > +Change into the boehm_gc directory of a clean check out of the Mercury system.
> > +The issue the command
> 
> s/The/Then/
> 
> Also, there should be a big warning at the top of the file saying that
> this process is difficult, and should not be undertaken lightly,
> and definitely not without discussing it on mercury-reviews first.
> 
> Otherwise that looks OK.
> 

diff -u upgrade_boehm_gc.html upgrade_boehm_gc.html
--- upgrade_boehm_gc.html
+++ upgrade_boehm_gc.html
@@ -15,6 +15,12 @@
 </H1>
 
 <P>
+<B>WARNING:</B> This process is difficult and should not be undertaken lightly.
+Before attempting to upgrade one should definitely discuss it on the
+mercury-reviews mailing list first.
+</P>
+
+<P>
 Download the required version of the
 <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">
 boehm garbage collector</A> from the
@@ -43,7 +49,8 @@
 <P>
 Import the new source on to the vendor branch.
 Note that gc_6_2alpha4 should be a tag which corresponds to
-the version of the collector that you are importing.
+the version of the collector that you are importing.<BR>
+<B>Warning:</B> this step can leave the repository in an inconsistent state.
 <PRE>
 # cvs import -I \! mercury/boehm_gc gc gc_6_2alpha4
 </PRE>
@@ -65,7 +72,7 @@
 <P>
 How to fix this problem.
 Change into the boehm_gc directory of a clean check out of the Mercury system.
-The issue the command
+Then issue the command
 <PRE>
 # cvs update .
 U BCC_MAKEFILE
@@ -121,7 +128,6 @@
 <PRE>
 # cvs update -j 1.1.1.6 -j 1.1.1.7 BCC_MAKEFILE
 </PRE>
-
 </P>
 
 <P>
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------