Newcomers' Guide to GHC Development

[Spiwack, Arnaud]

Hi,

I've just gone through the document, I have few comments:

- The dependencies instruction are too complex and long-winded. I'd start
by: if you are a nix user, use <Alp's nix derivation>, otherwise you need
<all this> installed [in particular, no sectioning of the dependencies!],
see <the relevant place> to find instruction for your particular system.
- The considerations about gitlab are mostly trivial and distract from the
point (at this point we're trying to build GHC): simply give a git clone
instruction from the main repository. (also highlight the fact that there
is a `--recursive`, it's easily missed, and give the `git submodule update
--init` back up in case it was forgotten, maybe?)
- Scrap the section called A note on Hadrian. It will just come up as
scary. The further reading section is sufficient to point to Hadrian issues
- devel2 is a good default flavour, but, when it comes up, you should also
include a link to a documentation that says: want to do X -> use flavour Y
- The idiom/stages seems to be a dead link, but maybe it'll work when this
document is transferred to the wiki?
- `git clean` is not sufficient to get to a pristine state, you need `git
clean -xdf && git submodule foreach 'git clean -xdf'`. It's probably even
better to just give the following one-liner: `git clean -xdf && git
submodule foreach 'git clean -xdf' && git submodule update --init`. Maybe
even even better, build.hs could have an option to call this one-liner?

/Arnaud

On Wed, Feb 27, 2019 at 11:07 AM Tobias Dammers <tdammers at gmail.com> wrote:

> Dear all,
>
> With the migration of our affairs from Trac to GitLab nearing
> completion, I would like to ask for a final round of feedback on the new
> Newcomers' Guide to GHC development.
>
> The draft can be found here:
>
>
> https://github.com/tdammers/ghc-wiki/blob/wip/newcomers/newcomers-tutorial.md
>
> TL;DR: If you have any kind of input / critique / praise regarding this
> document, feel free to reply, or, even better, issue a PR on github.
>
>
> Some background:
>
> The purpose of this document is to provide potential contributors with a
> practical, no-nonsense tutorial, guiding them from "I know nothing about
> GHC development" to their first successful merge request.
>
> The document has been compiled using existing wiki content, revised and
> edited to match the current state of affairs (particularly using Hadrian
> as the recommended build system), and to tune it to the target audience
> of first-time contributors. As such, we avoid going off on tangents
> (e.g., we do not explain how to use the make-based alternative build
> system), and we only explain what you need to understand in order to get
> going (e.g., we do not provide a complete run-down of all hadrian
> options).
>
> A few nonlinearities were deemed necessary in order to make the tutorial
> suitable across target platforms; Windows in particular requires some
> special attention. Other than that, however, we try to provide as linear
> an experience as we reasonably can.
>
>
> So with that said; all feedback and suggestions on this are welcome. We
> have gotten some great responses already, but I'd like to gather one
> more round of feedback before merging it into the freshly-migrated
> Haskell Wiki on GitLab.
>
> Thank you for your attention!
>
> --
> Tobias Dammers - tdammers at gmail.com
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20190228/463028a7/attachment.html>