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 <[email protected]> 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 - [email protected] > _______________________________________________ > ghc-devs mailing list > [email protected] > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs >
_______________________________________________ ghc-devs mailing list [email protected] http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
