Minor doc patch for ghc 7.10 + did I submit the patch correctly/follow the process?

[Austin Seipp]

Hi Doug,

On Tue, Mar 17, 2015 at 2:54 PM, Doug Burke <dburke.gw at gmail.com> 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/