Updating Haddock submodule

[Iavor Diatchki]

Hello,

here is a bit of git theory that may be useful:

  - a git repository is a graph, where each node is a *commit* (it
identifies the state of the entire repo), and the edges keep track of what
happened after what.

  - a *branch* is a pointer to a specific commit, where we plan to extend
the graph.   When we add a new commit to some branch, we link the commit to
wherever the branch points, and then we move the branch pointer to the new
commit.  Thus, the branches of a repository are the roots of the graph.

   - *HEAD* points to the "current" commit for a repo.  Typically, HEAD
points to the same place as one of the branches (we say that we are "on
that branch").  When we checkout a branch, we just move HEAD to point to
the same place as that branch.   If HEAD does not point to the same place
as any branch, we say that we are in a "detached HEAD state".   Making a
commit in a "detached HEAD state" is bad, because this results in a graph
node that is not reachable from any of the branches (i.e., roots), and it
would get lost if we were to GC the repo.

   - a *sub-module* remembers to a specific commit of a different repo.
 When we get a submodule, the different repo is downloaded and its HEAD is
moved to point to the specific commit (the command "git submodule update"
does this for all registered sub-modules).  In this way, we know that we
are always using the exact same version of the source code, no matter who
was committing what to the different repo.   Because of this, the submodule
repo will often end up in a "detached HEAD" state.  This is why before you
commit to it, you have to make sure that you are on a branch (e.g.,
"master").  To move around the "sub-module" pointer: 1) move the HEAD of
the sub-module repo (e.g., haddock) to the commit that you want, and 2)
add/commit the sub-module change to the parent repo (e.g., GHC)

-Iavor

















On Tue, Jul 15, 2014 at 12:01 AM, Simon Peyton Jones <simonpj at microsoft.com>
wrote:

>  Herbert, Austin
>
> 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.
>
> Can I humbly implore you both (or someone) to write down the workflow so
> that git-naïve people like me can do this with confidence, rather than (as
> now) in fear?
>
> 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.
>
> Please in writing the workflow, document every step as I have done below.
>
> Thanks!
>
> Simon
>
>
>
> 1.      *Starting point*:
>
> ·         all changes made in GHC and in utils/haddock.
>
> ·         validate works
>
> 2.      cd utils/haddock
>
> 3.      git stash
> Keep my changes out of the way
>
> 4.      git branch –av
> Keep the output
>
> *5.      *git checkout master
> *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.*
>
> 6.      Check that in the output of step 4, the current branch (which
> should be detatched-head) is the same commit as origin/master.
>
> *I have no idea what to do if this isn’t the case.*
>
> 7.      git pull
> Now Haddock’s ‘master’ is up to date
>
> 8.      git stash pop
> Apply the changes to the Haddock master branch
>
> 9.      git add/commit to record and commit the patch as usual
>
> 10.  git push
>
> *Phew!  At this stage we have updated Haddock.  I think.*
>
> 11.  cd ../..    Back into main ghc repo
>
> 12.  git add/commit    to record patch as usual, but
>
> ·         include utils/haddock in the “files” you add.  This will update
> the submodule pointer in the ghc repo
>
> ·         include the word “submodule” in the commit message
>
> 13.  git push
>
> *At this stage we have updated GHC too*
>
> 14.  ????      to get utils/haddock back into the detached-head state.
>
> *How do I do this?  git submodule update doesn’t*
>
>
>
>
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/ghc-devs/attachments/20140716/f6970f2c/attachment-0001.html>