Updating Haddock submodule
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
Simon, I'm surprised that you used 'git stash'/'git stash pop'. Why not use a branch and then merge it into master (possibly with rebasing)? That's what I would do. But if for some reason it is necessary to use 'git stash' then it would be good to have that reason documented in the workflow as well. Janek
I used stash to avoid creating and then deleting a branch. No deeper reason. Simon | -----Original Message----- | From: Jan Stolarek [mailto:jan.stolarek@p.lodz.pl] | Sent: 15 July 2014 08:53 | To: ghc-devs@haskell.org | Cc: Simon Peyton Jones; Herbert Valerio Riedel; 'Austin Seipp' | Subject: Re: Updating Haddock submodule | | Simon, | | I'm surprised that you used 'git stash'/'git stash pop'. Why not use a | branch and then merge it into master (possibly with rebasing)? That's | what I would do. But if for some reason it is necessary to use 'git | stash' then it would be good to have that reason documented in the | workflow as well. | | Janek
I'd like to humbly second this request... and specifically, that I more often use git in fear rather than confidence, especially when I'm working with ghc. This is perhaps inevitable -- a complicated system requires complicated tools. But, any help here is greatly appreciated.
As a very minor point:
On Jul 15, 2014, at 3:01 AM, Simon Peyton Jones
12. git add/commit to record patch as usual, but
That line confused me. I thought there was a new command `add/commit`! It didn't take too long to unravel the meaning, but I'd like to request that we avoid *any* abbreviations, especially in typewriter font. Thanks to the git-wizards who help us git-gits! Richard
On 07/15/2014 09:01 AM, Simon Peyton Jones 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@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Is https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git/Submodules#Maki... what you are looking for? Basically in step 12, you do your GHC hacking. Git should also show you a one line change with a commit reference which is your updated Haddock. You should commit that as well. Not sure why you have step 14, it seems to me that you should be good after 13. At step 14 you will already be pointing to the appropriate commit, it will just happen to be the same as the master branch at that point too so I think you're done. -- Mateusz K.
| Is | https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git/Submodules | #MakingchangestoGHCsubmodules | what you are looking for? Yes, it's the right kind of thing. I failed to find that, apologies. But - the page is advertised as work in progress - it checks out 'master'. Is that always right? perhaps not (see my comments) - it assumes you have anticipated the need for change before you do them Much more likely is my situation in which I altered my tree and then thought "oh now I have to commit" - it's at the bottom of a long page, most of which is irrelevant if you use ./sync-all (I think??) More generally I think I just need a bit more hand-holding for this process. Examples of expected output at the various stages would be useful. (I didn't include those in my writeup, but I should have.) | Basically in step 12, you do your GHC hacking. Git should also show you | a one line change with a commit reference which is your updated | Haddock. | You should commit that as well. There's an example of the need for an example. How does it display that one line change? What command makes it do so. | Not sure why you have step 14, it seems to me that you should be good | after 13. At step 14 you will already be pointing to the appropriate | commit, it will just happen to be the same as the master branch at that | point too so I think you're done. OK. But the current page clearly states that submodules should be in a detatched-head state, and it plainly isn't at that moment. Perhaps that's fine, but an unequivaocal statement that it's fine would be super helpful. I'm *not* complaining -- just trying to articulate explicitly what would be helpful to me (or other ill-informed people) next time. Thanks SImon | | -- | Mateusz K. | _______________________________________________ | ghc-devs mailing list | ghc-devs@haskell.org | http://www.haskell.org/mailman/listinfo/ghc-devs
On 2014-07-17 at 08:54:32 +0200, Simon Peyton Jones wrote: [...]
- it's at the bottom of a long page, most of which is irrelevant if you use ./sync-all (I think??)
Fwiw, the page was written to be a `./sync-all`-agnostic on purpose (in fact, ./sync-all isn't mentioned only once for pre-submodule trees) [...]
I'm *not* complaining -- just trying to articulate explicitly what would be helpful to me (or other ill-informed people) next time.
Maybe we need different two different presentations. One concise reference-like wiki page for Git-gnostic devs, and one for `./sync-all`-accustomed devs (or maybe even a rosetta-stone like translation between 'sync-all' invocations, and what the respective Git-only commands look like) Fwiw, I have started experimenting with a `runghc`-based ./sync-all replacement[1] (which uses only the packages bundled with GHC), but I don't have time to work on it for the next couple of weeks. Cheers, hvr [1]: Currently, it's more of a ghc.git advisor, checking the current state of your Git repo, and telling you what commands you should invoke next, but it's in its really earliest stages. If anyone wants to pick it up, and work on it, lemme know.
| Maybe we need different two different presentations. One concise | reference-like wiki page for Git-gnostic devs, and one for `./sync- | all`-accustomed devs (or maybe even a rosetta-stone like translation | between 'sync-all' invocations, and what the respective Git-only | commands look like) Maybe so. But we *certainly* need the one for people who are not Git-gnostic. WE provide sync-all, and advise its use for most folk, precisely because it automates a number of tricky corners. So our primary Git-un-gnostic documentation should be directed at that workflow. By all means there can be more implementation detail behind it, for Git gurus. I'm begging for it. Begging! Humbly! Simon | -----Original Message----- | From: Herbert Valerio Riedel [mailto:hvriedel@gmail.com] | Sent: 17 July 2014 09:20 | To: Simon Peyton Jones | Cc: Mateusz Kowalczyk; ghc-devs@haskell.org | Subject: Re: Updating Haddock submodule | | On 2014-07-17 at 08:54:32 +0200, Simon Peyton Jones wrote: | | [...] | | > - it's at the bottom of a long page, most of which is irrelevant if | > you use ./sync-all (I think??) | | Fwiw, the page was written to be a `./sync-all`-agnostic on purpose (in | fact, ./sync-all isn't mentioned only once for pre-submodule trees) | | [...] | | > I'm *not* complaining -- just trying to articulate explicitly what | > would be helpful to me (or other ill-informed people) next time. | | Maybe we need different two different presentations. One concise | reference-like wiki page for Git-gnostic devs, and one for `./sync- | all`-accustomed devs (or maybe even a rosetta-stone like translation | between 'sync-all' invocations, and what the respective Git-only | commands look like) | | Fwiw, I have started experimenting with a `runghc`-based ./sync-all | replacement[1] (which uses only the packages bundled with GHC), but I | don't have time to work on it for the next couple of weeks. | | | Cheers, | hvr | | [1]: Currently, it's more of a ghc.git advisor, checking the current | state of your Git repo, and telling you what commands you should | invoke next, but it's in its really earliest stages. If anyone | wants to pick it up, and work on it, lemme know.
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
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@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
participants (6)
-
Herbert Valerio Riedel -
Iavor Diatchki -
Jan Stolarek -
Mateusz Kowalczyk -
Richard Eisenberg -
Simon Peyton Jones