Hi Doug, thank you for describing the steps you took to submit a code review. That's quite useful. Your patch looks good too.

b) ask if I did this the right way; I'm happy to write this up as an addendum to the newcomers guide/something else on the wiki if it is a sensible path for a doc-only patch

Those steps you mention seem about right. Only this would have gotten you there somewhat sooner: https://ghc.haskell.org/trac/ghc/wiki/Building/GettingTheSources#Gettingabra... I don't think that the Newcomers page should have to mention that specific link however, because: 1. almost all patches are made for the master branch. That release notes file could be the only exception. 2. the wiki contains a lot of information that would be useful to read for newcomers, but we can't link to all of them 3. there is already a link to https://ghc.haskell.org/trac/ghc/wiki/Building/GettingTheSources 4. you proved you could make it happen without it Other things you mentioned:

1) I did not create a ticket; should I have done so?

Just a Phabricator code review is ok for small patches. Since we started using Phabricator, quite a few patches have been submitted and accepted without a ticket number. This workflow is however not mentioned on the wiki yet.

downloading the submodules seems excessive for a doc-only patch Maybe, but it's also more simple to just have one explanation for how to get the sources instead of two. But if you think the Newcomers page could be improved, please feel free to edit it.

-Thomas P.S. The Newcomers page makes you download from Github to prevent git.haskell.org from becomming overloaded when the Newcomers page gets linked from reddit.

Hi Doug, On Tue, Mar 17, 2015 at 2:54 PM, Doug Burke wrote:

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/