Newcomers' Guide to GHC Development

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Newcomers' Guide to GHC Development

Tobias Dammers
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 - [hidden email]
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

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

_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Newcomers' Guide to GHC Development

Julian Leviston-2
In reply to this post by Tobias Dammers
Hi,

Pretty glad someone’s updating the guide!

The updated version could be improved by shaping it into clearer sections because we’d like newcomers to feel like it’s light and easy. Layers is a great way to achieve this.

The first time I ran through the task list (not very long ago), it felt light and easy. This was because it was chunked well.

So, my suggestion would be to have a third sentence/paragraph in the introduction section that explains what the overall steps are that we’re going to explain next. Provide links down into those sections, and make it really clear that those sections are sections, if possible.

“Contributing to GHC is a simple process conceptually: it consists of [setting up your build tooling], [finding an issue/feature] for you to work on, [working on the code], then getting it [approved and merged].”

At each section, you could reiterate how to do that driving from the overarching aim of the explanation for the section. (Having an introduction to each section would help here, too).

For example, having a canonical way to determine what a good issue or feature to start on would be awesome, as would having somewhat of a mentor/buddy to help new users when working on their bugs (ie one or two people assigned to a newcomers’ first two or so tickets to help them through any issues until they feel confident). Not sure if our contributors allow for such things yet, tho.

Nice effort so far!
Julian

On 27 Feb 2019, at 9:06 pm, Tobias Dammers <[hidden email]> 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 - [hidden email]
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Newcomers' Guide to GHC Development

Tobias Dammers
In reply to this post by Spiwack, Arnaud
On Thu, Feb 28, 2019 at 12:43:12PM +0100, Spiwack, Arnaud wrote:
> - 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.

One consideration with this guide is that we want to reduce the amount
of indirection - the current "getting started" guide is very close to
being just a chaotic collection of links, and if you follow them all to
exhaustion, you will get lost and confused long before you manage to
make your first successful build (I know I did). So we decided to keep
the main narrative entirely in this document, providing links to other
pages and resources only for optional steps or unusual situations.

The nix-based setup is certainly a good idea though, and I do agree that
shortening this section further would be a good thing, so I will
definitely look into it again. Please keep in mind however that we
cannot possibly cater to all potential needs; we need to strike a
balance.

> - 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.

This was originally in the document; however, the goal here is not just
to build GHC (there are separate instructions for that), but to actually
issue a MR, and for that, you are supposed to create a fork. So we
instruct people to do that right away, and then clone the fork, rather
than clone the main repo and then modify their working copy to point to
the fork later.

> (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?)

Makes sense, I will add that.

> - 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

The purpose of this is not to scare people off, but to avoid confusion
when running into unexpected issues. Hadrian *is* a complex beast, and
quite new, and experience shows that people still encounter issues. The
intended message here is "if it doesn't work, it may not be your fault".
I will reword.

> - 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

In the interest of keeping things short, I'm inclined to say let's not
do that, and rely on the links we're already providing. (Those do not
work properly from within the github rendering of this page, but will be
fine if viewed from within gitlab; you should also be able to figure out
what the corresponding wiki pages on the old Trac wiki are).

> - The idiom/stages seems to be a dead link, but maybe it'll work when this
> document is transferred to the wiki?

Yes, it should. I have pushed this page to a development gitlab
instance, and the link seems to work fine there. See above.

> - `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?

Not a fan of tying SCM concerns into the build system. Rest seems
reasonable, although choice of git clean details may be up to the
individual (e.g. -f vs. -i).

Anyhow, thanks a lot for your feedback.
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Newcomers' Guide to GHC Development

Tobias Dammers
In reply to this post by Julian Leviston-2
Hi, thanks for your feedback.

I'll get into some detail below.

On Sat, Mar 02, 2019 at 11:36:06AM +1100, Julian Leviston wrote:

> The updated version could be improved by shaping it into clearer
> sections because we’d like newcomers to feel like it’s light and easy.
> Layers is a great way to achieve this.
>
> The first time I ran through the task list (not very long ago), it
> felt light and easy. This was because it was chunked well.
>
> So, my suggestion would be to have a third sentence/paragraph in the
> introduction section that explains what the overall steps are that
> we’re going to explain next. Provide links down into those sections,
> and make it really clear that those sections are sections, if
> possible.

I like the idea of a short outline of the overall progression in the
introduction, so just added that. I won't add those links yet, because
due to the way this works in Gitlab, it's best to do it after the
document has solidified, because adding or removing headers (of any
level) will change the headers' generated ID properties, potentially
breaking any links.

As far as the chunking goes, I believe we already have a fairly decent
structure in place. The GitHub layout may not make it very obvious
though, and I think it'll be clearer on Gitlab. I did rearrange things a
tiny bit in order to fit in better with the overall arch though.

If you have concrete suggestions on how to improve the structure
further, please feel free to tell, or better yet, issue a PR on GitHub.

> At each section, you could reiterate how to do that driving from the
> overarching aim of the explanation for the section. (Having an
> introduction to each section would help here, too).

This seems like overkill to me. We need to strike a balance between
completeness and brevity, and we're bordering on "too long" already. I
did try to come up with suitable introductions, but they all ended being
paraphrasings of the title or the entire section, so I decided against
them.

Note that my goal here is to remove obstacles and friction, not to
persuade people into contributing - by the time you read this guide, you
should have been persuaded already.

Quoting the very first sentence in the guide:

| This page is intended to serve as the first stop for those people who
| say, "I want to contribute to GHC, but I don't know quite where to
| begin."


> For example, having a canonical way to determine what a good issue or
> feature to start on would be awesome, as would having somewhat of a
> mentor/buddy to help new users when working on their bugs (ie one or
> two people assigned to a newcomers’ first two or so tickets to help
> them through any issues until they feel confident). Not sure if our
> contributors allow for such things yet, tho.

I agree that that would be awesome; however, we have limited resources
at our disposal that we need to juggle between several concerns, and
mentoring newcomers is only one of them.

What we can offer right now is:

- Issues labeled "newcomers" (the guide already mentions these)
- Ad-hoc, no-strings-attached support from core GHC contributors and
  various volunteers via this mailing list and IRC (the guide mentions
  these, too)
- Some time from core contributors, as available, allocated to handling
  incoming issues and merge requests. We strive to provide feedback on
  every one of them, but we cannot make any hard promises as to the
  timeframe, and we have to prioritize.

On top of that, many individuals and third-party organisations run
various forms of mentoring, tutoring, guidance, hackathon events,
counseling, etc. Listing those would go way beyond the scope of this
document, but you should have little trouble getting suggestions via our
various communication channels.

Hope that clarifies things, and again, thanks a lot for your input.
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

RE: Newcomers' Guide to GHC Development

Alexandre Rodrigues

Hello;

I’d like to ask something regarding this effort. Right now, GHC’s repository is mirrored in these locations:

 

Most of these have associated READMEs that encourage users to contribute patches to that particular instance, which does not really reflect the current state of affairs: right now, it is my understanding that GitLab is where all (new) patches are to be submitted.

 

With the recent migration to GitLab and archival of Trac, will the first two be moved to read-only status like the Trac service?

Regarding GitHub/GitLab – do we still want to accept contributions to GitHub? If so, what kind? All kinds? Maybe just small documentation patches?

 

I believe all of this should be documented to avoid fragmentation of contribution efforts. I still remember my first contribution was a little confusing because of this.

 


From: ghc-devs <[hidden email]> on behalf of Tobias Dammers <[hidden email]>
Sent: Tuesday, March 5, 2019 11:54:34 AM
To: GHC Devs
Subject: Re: Newcomers' Guide to GHC Development
 
Hi, thanks for your feedback.

I'll get into some detail below.

On Sat, Mar 02, 2019 at 11:36:06AM +1100, Julian Leviston wrote:

> The updated version could be improved by shaping it into clearer
> sections because we’d like newcomers to feel like it’s light and easy.
> Layers is a great way to achieve this.
>
> The first time I ran through the task list (not very long ago), it
> felt light and easy. This was because it was chunked well.
>
> So, my suggestion would be to have a third sentence/paragraph in the
> introduction section that explains what the overall steps are that
> we’re going to explain next. Provide links down into those sections,
> and make it really clear that those sections are sections, if
> possible.

I like the idea of a short outline of the overall progression in the
introduction, so just added that. I won't add those links yet, because
due to the way this works in Gitlab, it's best to do it after the
document has solidified, because adding or removing headers (of any
level) will change the headers' generated ID properties, potentially
breaking any links.

As far as the chunking goes, I believe we already have a fairly decent
structure in place. The GitHub layout may not make it very obvious
though, and I think it'll be clearer on Gitlab. I did rearrange things a
tiny bit in order to fit in better with the overall arch though.

If you have concrete suggestions on how to improve the structure
further, please feel free to tell, or better yet, issue a PR on GitHub.

> At each section, you could reiterate how to do that driving from the
> overarching aim of the explanation for the section. (Having an
> introduction to each section would help here, too).

This seems like overkill to me. We need to strike a balance between
completeness and brevity, and we're bordering on "too long" already. I
did try to come up with suitable introductions, but they all ended being
paraphrasings of the title or the entire section, so I decided against
them.

Note that my goal here is to remove obstacles and friction, not to
persuade people into contributing - by the time you read this guide, you
should have been persuaded already.

Quoting the very first sentence in the guide:

| This page is intended to serve as the first stop for those people who
| say, "I want to contribute to GHC, but I don't know quite where to
| begin."


> For example, having a canonical way to determine what a good issue or
> feature to start on would be awesome, as would having somewhat of a
> mentor/buddy to help new users when working on their bugs (ie one or
> two people assigned to a newcomers’ first two or so tickets to help
> them through any issues until they feel confident). Not sure if our
> contributors allow for such things yet, tho.

I agree that that would be awesome; however, we have limited resources
at our disposal that we need to juggle between several concerns, and
mentoring newcomers is only one of them.

What we can offer right now is:

- Issues labeled "newcomers" (the guide already mentions these)
- Ad-hoc, no-strings-attached support from core GHC contributors and
  various volunteers via this mailing list and IRC (the guide mentions
  these, too)
- Some time from core contributors, as available, allocated to handling
  incoming issues and merge requests. We strive to provide feedback on
  every one of them, but we cannot make any hard promises as to the
  timeframe, and we have to prioritize.

On top of that, many individuals and third-party organisations run
various forms of mentoring, tutoring, guidance, hackathon events,
counseling, etc. Listing those would go way beyond the scope of this
document, but you should have little trouble getting suggestions via our
various communication channels.

Hope that clarifies things, and again, thanks a lot for your input.
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

RE: Newcomers' Guide to GHC Development

Ben Gamari-2
Alexandre Rodrigues <[hidden email]> writes:

> Hello;
>
> I’d like to ask something regarding this effort. Right now, GHC’s
> repository is mirrored in these locations:
>
>   *   Phabricator<https://phabricator.haskell.org/diffusion/GHC/>
>   *   git.haskell.org<https://git.haskell.org/>
>   *   GitHub<https://github.com/ghc/ghc/>
>   *   GitLab<https://gitlab.haskell.org/ghc/ghc/>
>
> Most of these have associated READMEs that encourage users to
> contribute patches to that particular instance, which does not really
> reflect the current state of affairs: right now, it is my
> understanding that GitLab is where all (new) patches are to be
> submitted.
>
> With the recent migration to GitLab and archival of Trac, will the
> first two be moved to read-only status like the Trac service?
>
Precisely; git.haskell.org and Phabricator will both be decommissioned.
However, we want to ensure that we keep archival copies of these
services around so this will take some time.

> Regarding GitHub/GitLab – do we still want to accept contributions to
> GitHub? If so, what kind? All kinds? Maybe just small documentation
> patches?
>
At the moment the plan is to continue accepting small documentation
patches and divert everything larger to GitLab.

> I believe all of this should be documented to avoid fragmentation of
> contribution efforts. I still remember my first contribution was a
> little confusing because of this.
>
Indeed this is on the queue. So far we've been trying
out best to keep the migration on track and keep moving the release
schedule chugging along, even if slowly. After this newcomer's guide is
finished we will turn our attention to cleaning up the remaining
documentation.

Cheers,

- Ben


_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

signature.asc (497 bytes) Download Attachment