<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
        {font-family:Wingdings;
        panose-1:5 0 0 0 0 0 0 0 0 0;}
@font-face
        {font-family:"Cambria Math";
        panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
        {font-family:Calibri;
        panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
        {margin-top:6.0pt;
        margin-right:0cm;
        margin-bottom:6.0pt;
        margin-left:0cm;
        font-size:11.0pt;
        font-family:"Calibri","sans-serif";
        mso-fareast-language:EN-US;}
a:link, span.MsoHyperlink
        {mso-style-priority:99;
        color:#0563C1;
        text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
        {mso-style-priority:99;
        color:#954F72;
        text-decoration:underline;}
p.MsoListParagraph, li.MsoListParagraph, div.MsoListParagraph
        {mso-style-priority:34;
        margin-top:6.0pt;
        margin-right:0cm;
        margin-bottom:6.0pt;
        margin-left:36.0pt;
        font-size:11.0pt;
        font-family:"Calibri","sans-serif";
        mso-fareast-language:EN-US;}
p.Code, li.Code, div.Code
        {mso-style-name:Code;
        margin-top:0cm;
        margin-right:0cm;
        margin-bottom:0cm;
        margin-left:36.0pt;
        margin-bottom:.0001pt;
        font-size:12.0pt;
        font-family:"Courier New";
        mso-fareast-language:EN-US;}
span.EmailStyle18
        {mso-style-type:personal-compose;
        font-family:"Calibri","sans-serif";
        color:windowtext;}
.MsoChpDefault
        {mso-style-type:export-only;
        font-family:"Calibri","sans-serif";
        mso-fareast-language:EN-US;}
.MsoPapDefault
        {mso-style-type:export-only;
        margin-top:6.0pt;
        margin-right:0cm;
        margin-bottom:6.0pt;
        margin-left:0cm;}
@page WordSection1
        {size:612.0pt 792.0pt;
        margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
        {page:WordSection1;}
/* List Definitions */
@list l0
        {mso-list-id:1212228727;
        mso-list-type:hybrid;
        mso-list-template-ids:1659503684 134807553 134807555 134807557 134807553 134807555 134807557 134807553 134807555 134807557;}
@list l0:level1
        {mso-level-number-format:bullet;
        mso-level-text:\F0B7;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:Symbol;}
@list l0:level2
        {mso-level-number-format:bullet;
        mso-level-text:o;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:"Courier New";}
@list l0:level3
        {mso-level-number-format:bullet;
        mso-level-text:\F0A7;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:Wingdings;}
@list l0:level4
        {mso-level-number-format:bullet;
        mso-level-text:\F0B7;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:Symbol;}
@list l0:level5
        {mso-level-number-format:bullet;
        mso-level-text:o;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:"Courier New";}
@list l0:level6
        {mso-level-number-format:bullet;
        mso-level-text:\F0A7;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:Wingdings;}
@list l0:level7
        {mso-level-number-format:bullet;
        mso-level-text:\F0B7;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:Symbol;}
@list l0:level8
        {mso-level-number-format:bullet;
        mso-level-text:o;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:"Courier New";}
@list l0:level9
        {mso-level-number-format:bullet;
        mso-level-text:\F0A7;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:Wingdings;}
@list l1
        {mso-list-id:1333728173;
        mso-list-type:hybrid;
        mso-list-template-ids:595518508 134807567 134807577 134807579 134807567 134807577 134807579 134807567 134807577 134807579;}
@list l1:level1
        {mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l1:level2
        {mso-level-number-format:alpha-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l1:level3
        {mso-level-number-format:roman-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:right;
        text-indent:-9.0pt;}
@list l1:level4
        {mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l1:level5
        {mso-level-number-format:alpha-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l1:level6
        {mso-level-number-format:roman-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:right;
        text-indent:-9.0pt;}
@list l1:level7
        {mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l1:level8
        {mso-level-number-format:alpha-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l1:level9
        {mso-level-number-format:roman-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:right;
        text-indent:-9.0pt;}
@list l2
        {mso-list-id:1804614846;
        mso-list-type:hybrid;
        mso-list-template-ids:-1893714864 -808150568 134807553 134807579 134807567 134807577 134807579 134807567 134807577 134807579;}
@list l2:level1
        {mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:"Times New Roman","serif";
        mso-ascii-font-family:Calibri;
        mso-hansi-font-family:Calibri;}
@list l2:level2
        {mso-level-number-format:bullet;
        mso-level-text:\F0B7;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;
        font-family:Symbol;}
@list l2:level3
        {mso-level-number-format:roman-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:right;
        text-indent:-9.0pt;}
@list l2:level4
        {mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l2:level5
        {mso-level-number-format:alpha-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l2:level6
        {mso-level-number-format:roman-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:right;
        text-indent:-9.0pt;}
@list l2:level7
        {mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l2:level8
        {mso-level-number-format:alpha-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:left;
        text-indent:-18.0pt;}
@list l2:level9
        {mso-level-number-format:roman-lower;
        mso-level-tab-stop:none;
        mso-level-number-position:right;
        text-indent:-9.0pt;}
ol
        {margin-bottom:0cm;}
ul
        {margin-bottom:0cm;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-GB" link="#0563C1" vlink="#954F72">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:12.0pt">Herbert, Austin<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt">I’ve just made a change to GHC that has a (trivial) knock-on effect in Haddock, so I had to update the submodule.  Here is what I did, after consulting Austin.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt">Can I humbly implore you both (or someone) to write down the workflow so that git-nave people like me can do this with confidence, rather than (as now) in fear?<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt">Below is my draft of the workflow.  It seems pretty complicated, and there are three places (in red) where I am unsure what to do.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt">Please in writing the workflow, document every step as I have done below.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt">Thanks!<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt">Simon<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt"><o:p> </o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">1.<span style="font:7.0pt "Times New Roman"">     
</span></span></span><![endif]><b><span style="font-size:12.0pt">Starting point</span></b><span style="font-size:12.0pt">:
<o:p></o:p></span></p>
<p class="MsoListParagraph" style="margin-left:72.0pt;text-indent:-18.0pt;mso-list:l2 level2 lfo3">
<![if !supportLists]><span style="font-size:12.0pt;font-family:Symbol"><span style="mso-list:Ignore"><span style="font:7.0pt "Times New Roman"">        
</span></span></span><![endif]><span style="font-size:12.0pt">all changes made in GHC and in utils/haddock.<o:p></o:p></span></p>
<p class="MsoListParagraph" style="margin-left:72.0pt;text-indent:-18.0pt;mso-list:l2 level2 lfo3">
<![if !supportLists]><span style="font-size:12.0pt;font-family:Symbol"><span style="mso-list:Ignore"><span style="font:7.0pt "Times New Roman"">        
</span></span></span><![endif]><span style="font-size:12.0pt">validate works<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">2.<span style="font:7.0pt "Times New Roman"">     
</span></span></span><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">cd utils/haddock<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">3.<span style="font:7.0pt "Times New Roman"">     
</span></span></span><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">git stash</span><span style="font-size:12.0pt"><br>
Keep my changes out of the way<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">4.<span style="font:7.0pt "Times New Roman"">     
</span></span></span><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">git branch –av</span><span style="font-size:12.0pt"><br>
Keep the output<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><i><span style="font-size:12.0pt"><span style="mso-list:Ignore">5.<span style="font:7.0pt "Times New Roman"">     
</span></span></span></i><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">git checkout master</span><span style="font-size:12.0pt"><br>
<i><span style="color:red">Why ‘master’?  Because I know from talking to Austin that the ghc repo tracks Haddock’s master branch.  There is no way to get this information without talking to Someone Who Knows.  There should be a wiki page that documents it</span>.<o:p></o:p></i></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">6.<span style="font:7.0pt "Times New Roman"">     
</span></span></span><![endif]><span style="font-size:12.0pt">Check that in the output of step 4, the current branch (which should be detatched-head) is the same commit as origin/master.<o:p></o:p></span></p>
<p class="MsoListParagraph"><i><span style="font-size:12.0pt;color:red">I have no idea what to do if this isn’t the case.<o:p></o:p></span></i></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">7.<span style="font:7.0pt "Times New Roman"">     
</span></span></span><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">git pull</span><span style="font-size:12.0pt"><br>
Now Haddock’s ‘master’ is up to date<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">8.<span style="font:7.0pt "Times New Roman"">     
</span></span></span><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">git stash pop</span><span style="font-size:12.0pt"><br>
Apply the changes to the Haddock master branch<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">9.<span style="font:7.0pt "Times New Roman"">     
</span></span></span><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">git add/commit</span><span style="font-size:12.0pt"> to record and commit the patch as usual<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">10.<span style="font:7.0pt "Times New Roman""> 
</span></span></span><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">git push<o:p></o:p></span></p>
<p class="MsoListParagraph"><b><span style="font-size:12.0pt">Phew!  At this stage we have updated Haddock.  I think.<o:p></o:p></span></b></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">11.<span style="font:7.0pt "Times New Roman""> 
</span></span></span><![endif]><span style="font-size:12.0pt">cd ../..    Back into main ghc repo<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">12.<span style="font:7.0pt "Times New Roman""> 
</span></span></span><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">git add/commit  
</span><span style="font-size:12.0pt"> to record patch as usual, but<o:p></o:p></span></p>
<p class="MsoListParagraph" style="margin-left:72.0pt;text-indent:-18.0pt;mso-list:l2 level2 lfo3">
<![if !supportLists]><span style="font-size:12.0pt;font-family:Symbol"><span style="mso-list:Ignore"><span style="font:7.0pt "Times New Roman"">        
</span></span></span><![endif]><span style="font-size:12.0pt">include utils/haddock in the “files” you add.  This will update the submodule pointer in the ghc repo<o:p></o:p></span></p>
<p class="MsoListParagraph" style="margin-left:72.0pt;text-indent:-18.0pt;mso-list:l2 level2 lfo3">
<![if !supportLists]><span style="font-size:12.0pt;font-family:Symbol"><span style="mso-list:Ignore"><span style="font:7.0pt "Times New Roman"">        
</span></span></span><![endif]><span style="font-size:12.0pt">include the word “submodule” in the commit message<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">13.<span style="font:7.0pt "Times New Roman""> 
</span></span></span><![endif]><span style="font-size:12.0pt;font-family:"Courier New"">git push<o:p></o:p></span></p>
<p class="MsoListParagraph"><b><span style="font-size:12.0pt">At this stage we have updated GHC too<o:p></o:p></span></b></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;mso-list:l2 level1 lfo3"><![if !supportLists]><span style="font-size:12.0pt"><span style="mso-list:Ignore">14.<span style="font:7.0pt "Times New Roman""> 
</span></span></span><![endif]><span style="font-size:12.0pt">????      to get utils/haddock back into the detached-head state.<o:p></o:p></span></p>
<p class="MsoListParagraph"><i><span style="font-size:12.0pt;color:red">How do I do this?  git submodule update doesn’t<o:p></o:p></span></i></p>
<p class="MsoListParagraph"><span style="font-size:12.0pt"><o:p> </o:p></span></p>
<p class="MsoListParagraph"><span style="font-size:12.0pt"><o:p> </o:p></span></p>
</div>
</body>
</html>