<div dir="ltr"><div>Hi,</div><div><br></div><div>I've just gone through the document, I have few comments:<br></div><div><br></div><div>- 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.<br></div><div>- 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?)<br></div><div>- 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<br></div><div>- 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</div>- The idiom/stages seems to be a dead link, but maybe it'll work when this document is transferred to the wiki?<br><div>- `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?</div><div><br></div><div>/Arnaud<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Feb 27, 2019 at 11:07 AM Tobias Dammers <<a href="mailto:tdammers@gmail.com">tdammers@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Dear all,<br>
<br>
With the migration of our affairs from Trac to GitLab nearing<br>
completion, I would like to ask for a final round of feedback on the new<br>
Newcomers' Guide to GHC development.<br>
<br>
The draft can be found here:<br>
<br>
<a href="https://github.com/tdammers/ghc-wiki/blob/wip/newcomers/newcomers-tutorial.md" rel="noreferrer" target="_blank">https://github.com/tdammers/ghc-wiki/blob/wip/newcomers/newcomers-tutorial.md</a><br>
<br>
TL;DR: If you have any kind of input / critique / praise regarding this<br>
document, feel free to reply, or, even better, issue a PR on github.<br>
<br>
<br>
Some background:<br>
<br>
The purpose of this document is to provide potential contributors with a<br>
practical, no-nonsense tutorial, guiding them from "I know nothing about<br>
GHC development" to their first successful merge request.<br>
<br>
The document has been compiled using existing wiki content, revised and<br>
edited to match the current state of affairs (particularly using Hadrian<br>
as the recommended build system), and to tune it to the target audience<br>
of first-time contributors. As such, we avoid going off on tangents<br>
(e.g., we do not explain how to use the make-based alternative build<br>
system), and we only explain what you need to understand in order to get<br>
going (e.g., we do not provide a complete run-down of all hadrian<br>
options).<br>
<br>
A few nonlinearities were deemed necessary in order to make the tutorial<br>
suitable across target platforms; Windows in particular requires some<br>
special attention. Other than that, however, we try to provide as linear<br>
an experience as we reasonably can.<br>
<br>
<br>
So with that said; all feedback and suggestions on this are welcome. We<br>
have gotten some great responses already, but I'd like to gather one<br>
more round of feedback before merging it into the freshly-migrated<br>
Haskell Wiki on GitLab.<br>
<br>
Thank you for your attention!<br>
<br>
-- <br>
Tobias Dammers - <a href="mailto:tdammers@gmail.com" target="_blank">tdammers@gmail.com</a><br>
_______________________________________________<br>
ghc-devs mailing list<br>
<a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a><br>
<a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs</a><br>
</blockquote></div>