[commit: ghc] master: Convert haddock into a proper submodule (re #8545) (34b0721)

[Herbert Valerio Riedel]

Hello Simon,

On 2014-03-24 at 09:37:32 +0100, Simon Peyton Jones wrote:
> OK. Some questions.
>
> · Where is a good place to get a conceptual understanding of
> submodules?

There were three links at the top of the Wiki page; I assume you want
something better than that?

> Concerning
> https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git/Submodules
>
> · Under "Updating an existing source tree clone" you say we have to do
> "git submodule update --init". What happens if we forget? Couldn't
> sync-all do that? (Indeed it now emits a message to that effect

sync-all can do that of course; at this point, I'm just collecting all
direct `git` commands one would have to enter if there wasn't a sync-all
script -- once everything is in place, a new radically stripped down
`sync-all` can be constructed for the common day-to-day invocations.

The page also aims to make the underlying Git commands more transparent,
with the hope that by explaining what happens under the hood, it may
become less confusing when `sync-all` fails.

> bash$ ./sync-all pull --rebase

Yes, sync-all does already call `git submodule update` in some occasions
already, but its current implementation is far more confusing than it
needs to be IMHO :-)


> · Under “Overriding pushurl”, same question. Couldn’t that long “git
> submodule foreach” command be done by sync-all?

yes, it will

(even though that specific invocation will be taken core by sync-all in
the future, that snippet serves as an example for the versatile 'git
submodule foreach' tool everyone working with submodules should at least
know about -- it's not that far-fetched that one might want to do
something non-standard sync-all doesn't handle)

> · Under “Making changes”, this looks hard to me. Is “base” a
> submodule? 
> Does that mean we have to remember to do some incantations before we
> modify base? 

Actually, we're strongly considering to fold the non-upgradable
GHC-specific packages tied to GHC, namely

 - base
 - ghc-prim
 - integer-{gmp,simple}
 - template-haskell

into ghc.git (as was done with testsuite/) as those wouldn't benefit
much from remaining an independent (submodule) repo anyway;

> What if you forget and make the modifications first?  Again, could
> some of this be automated, at least for the common workflow of
> pull/push?

for one, if you forget to associate a Git branch before committing on a
detached-HEAD, you can simply 'git push origin HEAD:master'

If you meant about forgetting to update ghc.git to point to the new
commit, then that's actually a feature to avoid *having* to track each
single push/commit to master of a submodule to ghc.git's master branch
as well; For instance, utils/haddock 'master' is currently one rather
unimportant commit[1] ahead of what 'ghc.git' references as its
haddock.git commit right now.

 [1]: http://git.haskell.org/haddock.git/commitdiff/f3c7cd34d066cd40cb4983893165de038974fd95