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@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.m...
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@gmail.com _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs