Hi Doug,
On Tue, Mar 17, 2015 at 2:54 PM, Doug Burke
1) I did not create a ticket; should I have done so? The existing documentation assumes that you are fixing a bug. It's not clearto me if "RFE to the docs" should be treated the same way
We like to have tickets for every revision. This is mostly because a ticket has more metadata; for example, I very regularly find out what I need to merge into the stable branch using tickets, not Phabricator. This occurs when people submit patches there, and change the status of the related ticket on Trac. This ensures I don't forget them, and it leaves a nice history in Trac about what-was-fixed-when. For small documentation changes like this, not having a ticket is fine; for future patches, you can simply use your better judgement on whether you think a full ticket is necessary. I don't think it is here.
2) since the master branch doesn't contain the 7.10 doc file, and the newcomer guide assumes you are working from the master branch, I did
# downloading the submodules seems excessive for a doc-only patch % git config --global url."git://github.com/ghc/packages-".insteadOf git://github.com/ghc/packages/ % git clone --recursive git://github.com/ghc/ghc % cd git % arc install-certificate ... enter in the token as requested % git checkout ghc-7.10 # as I'm on a very slow download link the repository needed to be updated, so % git fetch origin % git pull origin ghc-7.10
FWIW, all of these steps can really be condensed into one: $ git clone -b ghc-7.10 --recursive git://git.haskell.org/ghc.git ghc-7.10 $ cd ghc-7.10/ $ ... hack hack hack ... This clones the 7.10 branch and all subrepositories. A similar incantation without the '-b' works for HEAD. In general, it's a bit easier to manage the branches by just using separate directories. You can use one directory, which is totally fine but it's easy to forget things like 'git submodule update' when you 'git checkout', and that's a bit annoying unfortunately. We should definitely fix the docs up a bit here.
# since some of these were in need of updating and 'arc diff' complained % git submodule update ... edit docs/users_guide/7.10.1-notes.xml
# just to check I didn't make any obvious snafus % xmllint 7.10.1-notes.xml % git diff
% git add 7.10.1-notes.xml % git commit -m '...'
# finally get to arc; the first time I tried it complained about a missing "branch" # so I guessed it made sense to use the branch I had started with, rather than the # suggested one (which I think was master) % arc diff ghc-7.10 ... edit the file and guess at what to put in for reviewers (which I just left as blank and fortunately it looks like it defaults to something sensible).
The easiest way to submit a review, although there are several workflows, is, IMO: $ git checkout -b my-new-branch $ ... hack hack hack ... $ git commit -sm "new thing" $ arc diff "HEAD~" This basically says "Send the latest patch against my current branch to Phabricator", which is normally what most people want, since they're just sending up a small diff. Then you can keep saying: $ ... hack hack hack ... $ git commit -am "fix some things" $ arc diff $ ... hack hack hack ... $ git commit -am "fix some things" $ arc diff which will keep updating that particular review. You can also always say: $ arc which which will tell you the logic Arcanist used to compute diffs and why it did something. I've been meaning to clean up the Phabricator documentation on the wiki for a while; there are a few particular things that can handle 99% of workflows, but right now the doc page is a bit crammed.
Which is a rather heavy weight process when all I wanted to do was re-organize several paragraphs of a text file!
Note that I was lazy and didn't try building ghc since it really is a simple doc change and I didn't want to go and spend even more time working out what I needed to build ghc documentation.
FWIW, you should just need DocBook, dblatex, etc. There are docs here: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation But also, we need to make it possible to build the documentation 'standalone', since right now it requires the build system (in some bizarre ways). Hopefully this will become easier when we move to AsciiDoc... In general our onboarding documentation could use a refactoring on this front. All suggestions appreciated! -- Regards, Austin Seipp, Haskell Consultant Well-Typed LLP, http://www.well-typed.com/