Newcomers' Guide to GHC Development

Tue Mar 12 23:35:14 UTC 2019

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?

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 <ghc-devs-bounces at haskell.org> on behalf of Tobias Dammers <tdammers at gmail.com>
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
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/20190312/4e85a533/attachment.html>