Thoughts on the Contributing page

older
RE: Thoughts on the Contributing...

Ben Gamari

19 Jan 2019 19 Jan '19

3:55 p.m.

For those following along at home: David has been looking at revising our contributor documentation. He has started consolidating a variety of relevant content on the Contributing page of the Wiki [1]. Below are my thoughts; feel free to chime in with your own. David, The contributing page is looking quite good. However, I do wonder whether we could reduce the link "fan-out" a bit more: it still rather feels like a collection of links with no clear "beginning". The "Newcomers to GHC" section is a great start but I see two potential issues: * we don't clearly articulate the precise steps that a newcomer will need to take * the first thing we mention are four links which, while useful, constitute a significant volume of reading for a newcomer. I fear we may lose people at this point. Regarding the second point, I think that WorkingConventions/FixingBugs is a good model in that it clearly lists a series of concrete steps that the contributor should take. Admittedly, I think some of the detail should be dropped or moved (e.g. the mention of setting git's user.name variable is likely unnecessary in 2019). I think that something similar to this list should be the first thing one sees when they reach the contributing page. Ideally the "typical" case of a new contributor wanting to submit their first patch would be able to gather everything they need to get started in one or two screenfuls of text. After that prose can come additional links to more in-depth documentation. Other various issues I noticed: * We link to wiki:WorkingConventions from a variety of places (including wiki:Contributing) but it is now just a link to wiki:Contributing. * wiki:WorkingConventions/FixingBugs still has references to Phabricator. In general we should start culling such references. * wiki:WorkingConventions/FixingBugs also has references to Trac documentation. We should try to replace these with the relevant GitLab documentation when we migrate. * wiki:WorkingConventions/FixingBugs should be updated to reflect that GitLab CI is now the source of truth for validation. * I don't know exactly how this should look but I think we need to do a better job of concisely stating what we expect of contributions. That is: * commit messages should be readable and discuss what the patch does. "Fixes #NNNN" is not an adequate commit message. * changes should be commented where necessary (my usual rule of thumb is "write the comment you would have liked to read when you started writing your patch"). We should mention the Note convention. * commit messages and comments should refer to ticket numbers where appropriate (e.g. using usual #NNNN syntax; people often get this wrong). * commits should be either squashed or logically distinct, individually buildable changes. * changes to most of `base` need to go through the CLC (this may be optional as defining what set of `base` this applies to is a bit tricky; in the interest of keeping things concise we may be better off handling this personally on a case-by-case basis) * code changes should conform to GHC's (somewhat fluid, for better or worse) code style (https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle) * thought should be given to testing Having a document which succinctly summarised these expectations as we could easily refer to it during code review. Even better, we could excerpt it as a checklist in our merge request description template (I have put up an initial attempt at this as !149). Anyways, there is more to be said here but this email is getting a bit long so let's leave it for future discussions. Cheers, - Ben [1] https://ghc.haskell.org/trac/ghc/wiki/Contributing

Attachments:

signature.asc (application/pgp-signature — 487 bytes)

Show replies by date

Tobias Dammers

23 Jan 23 Jan

3:47 a.m.

On Sat, Jan 19, 2019 at 03:55:06PM -0500, Ben Gamari wrote:

...

For those following along at home:

David has been looking at revising our contributor documentation. He has started consolidating a variety of relevant content on the Contributing page of the Wiki [1]. Below are my thoughts; feel free to chime in with your own.

David,

The contributing page is looking quite good. However, I do wonder whether we could reduce the link "fan-out" a bit more: it still rather feels like a collection of links with no clear "beginning".

...

The "Newcomers to GHC" section is a great start but I see two potential issues:

* we don't clearly articulate the precise steps that a newcomer will need to take

* the first thing we mention are four links which, while useful, constitute a significant volume of reading for a newcomer. I fear we may lose people at this point.

Agree; fan-out superficially seems like a good idea (more information is good, right?), but it just ends up overwhelming and confusing people here. More information can be linked to later; the "Newcomers' Guide" should have a clear narrative, with highly opinionated, well-tested steps that will lead you from "I have nothing" to "Baby's First Merge Request" and essentially Just Work.

...

Regarding the second point, I think that WorkingConventions/FixingBugs is a good model in that it clearly lists a series of concrete steps that the contributor should take. Admittedly, I think some of the detail should be dropped or moved (e.g. the mention of setting git's user.name variable is likely unnecessary in 2019).

I think that something similar to this list should be the first thing one sees when they reach the contributing page. Ideally the "typical" case of a new contributor wanting to submit their first patch would be able to gather everything they need to get started in one or two screenfuls of text. After that prose can come additional links to more in-depth documentation.

Exactly.

...

Other various issues I noticed:

* We link to wiki:WorkingConventions from a variety of places (including wiki:Contributing) but it is now just a link to wiki:Contributing.

...

* wiki:WorkingConventions/FixingBugs still has references to Phabricator. In general we should start culling such references.

* wiki:WorkingConventions/FixingBugs also has references to Trac documentation. We should try to replace these with the relevant GitLab documentation when we migrate.

* wiki:WorkingConventions/FixingBugs should be updated to reflect that GitLab CI is now the source of truth for validation.

A good first step, I think, would be to simply grep the entire wiki for terms like "phab", "trac", etc., which is going to be significantly easier after the migration due to gitlab's wiki being a git repo of markdown files, rather than SQL-backed. If we're pressed for man-hours, it might even be best to just delete outdated pages, and evolve new material as the need arises.

...

* I don't know exactly how this should look but I think we need to do a better job of concisely stating what we expect of contributions. That is:

* commit messages should be readable and discuss what the patch does. "Fixes #NNNN" is not an adequate commit message.

* changes should be commented where necessary (my usual rule of thumb is "write the comment you would have liked to read when you started writing your patch"). We should mention the Note convention.

* commit messages and comments should refer to ticket numbers where appropriate (e.g. using usual #NNNN syntax; people often get this wrong).

* commits should be either squashed or logically distinct, individually buildable changes.

* changes to most of `base` need to go through the CLC (this may be optional as defining what set of `base` this applies to is a bit tricky; in the interest of keeping things concise we may be better off handling this personally on a case-by-case basis)

* code changes should conform to GHC's (somewhat fluid, for better or worse) code style (https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle)

* thought should be given to testing

Having a document which succinctly summarised these expectations as we could easily refer to it during code review. Even better, we could excerpt it as a checklist in our merge request description template (I have put up an initial attempt at this as !149).

I believe this should be a separate, self-contained document; we should not overload the New Contributors' Guide with this information, nor should it be scattered across the rest of the documentation (though more pages should exist to go into full detail on each of those points). The New Contributors' Guide should, however, follow these practices and thus document them by example. E.g., the tutorial should include a step where you squash your commits and add suitable comments. Likewise, the NOTE: convention can be introduced simply by walking through the steps as part of the tutorial. On a completely unrelated note, I was thinking that it may be feasible and desirable to hack up a quick broken-links check for the wiki, possibly even as part of the migration script (which has to extract wiki links anyway as it goes, and also visits every wiki page at some point, so maintaining a list of links and then crossing off the ones that exist shouldn't be a huge effort). Armed with such a list, we could then semi-automatically deal with broken links and redirects as part of a cleanup sweep. I'll have to give redirects a bit more thought in this context though.

Ben Gamari

12:54 p.m.

Tobias Dammers writes:

...

On Sat, Jan 19, 2019 at 03:55:06PM -0500, Ben Gamari wrote:

...
...

I believe this should be a separate, self-contained document; we should not overload the New Contributors' Guide with this information, nor should it be scattered across the rest of the documentation (though more pages should exist to go into full detail on each of those points). The New Contributors' Guide should, however, follow these practices and thus document them by example. E.g., the tutorial should include a step where you squash your commits and add suitable comments. Likewise, the NOTE: convention can be introduced simply by walking through the steps as part of the tutorial.

Sounds like we are largely in agreement. Let's start on this after the Trac migration is finished.

...

On a completely unrelated note, I was thinking that it may be feasible and desirable to hack up a quick broken-links check for the wiki, possibly even as part of the migration script (which has to extract wiki links anyway as it goes, and also visits every wiki page at some point, so maintaining a list of links and then crossing off the ones that exist shouldn't be a huge effort). Armed with such a list, we could then semi-automatically deal with broken links and redirects as part of a cleanup sweep. I'll have to give redirects a bit more thought in this context though.

I was going to recommend we rather just use something off-the-shelf to avoid reinventing the wheel. I use linkchecker [1] elsewhere and it works quite well. I believe you can use its -W flag to catch non-existent wiki pages (which won't return a 404). Of course, if it's easier to do this as part of the migration script then that is also fine. Cheers, - Ben

Tobias Dammers

24 Jan 24 Jan

3:09 a.m.

On Wed, Jan 23, 2019 at 12:54:51PM -0500, Ben Gamari wrote:

...

...
Sounds like we are largely in agreement. Let's start on this after the Trac migration is finished.

I can in fact start working on this already while the migration is pipelined. It's just markdown in git, so writing a draft and then merging it into the wiki is perfectly straightforward.

...

I was going to recommend we rather just use something off-the-shelf to avoid reinventing the wheel. I use linkchecker [1] elsewhere and it works quite well. I believe you can use its -W flag to catch non-existent wiki pages (which won't return a 404).

Ofc, if we can do it without any extra coding effort, all the better. I do think doing it as part of the migration script might make it easier to capture those "redirect" pages (e.g. https://ghc.haskell.org/trac/ghc/wiki/Newcomers): we're scraping anyway, so I think detecting the shape of those pages shouldn't be overly difficult, and might be something an off-the-shelf link checker isn't as suitable for.

Tobias Dammers

29 Jan 29 Jan

4:14 a.m.

On Sat, Jan 19, 2019 at 03:55:06PM -0500, Ben Gamari wrote:

...

For those following along at home:

David has been looking at revising our contributor documentation. He has started consolidating a variety of relevant content on the Contributing page of the Wiki [1]. Below are my thoughts; feel free to chime in with your own.

One more thought I'd like to throw out in the open here: The current Newcomers' Guide uses the current Makefile workflow, but this is on a fast track to deprecation - but then, I doubt Hadrian has seen enough exposure yet to use for a good beginner-friendly "Just Works" guide. I'm leaning towards sticking with make for now, also because existing material is already written this way; and then once Hadrian is truly ready for prime time, we can rewrite the relevant parts. Thoughts?

Julian Leviston

3:09 p.m.

...

On 29 Jan 2019, at 8:14 pm, Tobias Dammers wrote:

The current Newcomers' Guide uses the current Makefile workflow, but this is on a fast track to deprecation - but then, I doubt Hadrian has seen enough exposure yet to use for a good beginner-friendly "Just Works" guide. I'm leaning towards sticking with make for now, also because existing material is already written this way; and then once Hadrian is truly ready for prime time, we can rewrite the relevant parts.

Thoughts?

As a recent newcomer, it’d be nice to have the option there as a link with a warning sign “here be dragons, but try this out if you’re interested”. I tried it. It seems better than regular make already (I don’t have to guess at appropriate concurrency, for example, I just throw -j at it and it works it out assumedly because GHC can work out the number of capabilities), and it seems to work out which builds it needs to do next automatically. Both those things - at least - are more beginner friendly than manually cloning the mk/build.mk file, running ./boot && ./configure && make -j8 then adjusting the mk/build.mk file again to get make to be faster. So, FWIW, I say put the link on the page at the top as an alternative, mark it with a warning saying something along the lines of that it might not work, but it’s the future, and it’s simpler and easier if it does, and feel free to try it out, then fallback to make. There are plenty of sharp rocks for beginners, and ironically the existing make-based build system is probably one of them. (Having said that, it’s very helpful to know the stages of compilation, so hopefully whatever docs we arrive at will point the beginner to something explaining what’s going on as they do their first bootstrapping build, for the curious. Julian

Tobias Dammers

30 Jan 30 Jan

9:55 a.m.

On Wed, Jan 30, 2019 at 07:09:25AM +1100, Julian Leviston wrote:

...

As a recent newcomer, it’d be nice to have the option there as a link with a warning sign “here be dragons, but try this out if you’re interested”. I tried it. It seems better than regular make already (I don’t have to guess at appropriate concurrency, for example, I just throw -j at it and it works it out assumedly because GHC can work out the number of capabilities), and it seems to work out which builds it needs to do next automatically. Both those things - at least - are more beginner friendly than manually cloning the mk/build.mk file, running ./boot && ./configure && make -j8 then adjusting the mk/build.mk file again to get make to be faster.

So, FWIW, I say put the link on the page at the top as an alternative, mark it with a warning saying something along the lines of that it might not work, but it’s the future, and it’s simpler and easier if it does, and feel free to try it out, then fallback to make. There are plenty of sharp rocks for beginners, and ironically the existing make-based build system is probably one of them. (Having said that, it’s very helpful to know the stages of compilation, so hopefully whatever docs we arrive at will point the beginner to something explaining what’s going on as they do their first bootstrapping build, for the curious.

Actually, after talking to both the Simons as well as Alp, one of the core people in the Hadrian project (if not the mastermind), we tentatively decided to write the Newcomers' Guide for Hadrian, not Make. In principle, Hadrian should be able to do everything that is needed for this, and the "regular" code paths have been tested extensively, and as you have noticed, it is a lot more user friendly. We may still want to link to the Make-based build instructions somewhere, but present Hadrian as the default option. A short explanation of build stages will of course still be in the Guide - they are just as relevant to Hadrian as they are to the Make build system. However, the tutorial is quite long as it is already, so I want to keep it as short as possible, delegating in-depth explanations to other (ideally existing) wiki pages. If you like, you can follow along with my progress: https://github.com/tdammers/ghc-wiki/blob/wip/newcomers/newcomers-tutorial.m...

Matthew Pickering

10:01 a.m.

Whilst we're at it, is there any consensus to make the default build settings more friendly to developers? The default is still perf which takes a very long time. devel2 would be an appropriate choice I think for newcomers. Matt On Wed, Jan 30, 2019 at 2:56 PM Tobias Dammers wrote:

...

On Wed, Jan 30, 2019 at 07:09:25AM +1100, Julian Leviston wrote:

...
As a recent newcomer, it’d be nice to have the option there as a link with a warning sign “here be dragons, but try this out if you’re interested”. I tried it. It seems better than regular make already (I don’t have to guess at appropriate concurrency, for example, I just throw -j at it and it works it out assumedly because GHC can work out the number of capabilities), and it seems to work out which builds it needs to do next automatically. Both those things - at least - are more beginner friendly than manually cloning the mk/build.mk file, running ./boot && ./configure && make -j8 then adjusting the mk/build.mk file again to get make to be faster.

So, FWIW, I say put the link on the page at the top as an alternative, mark it with a warning saying something along the lines of that it might not work, but it’s the future, and it’s simpler and easier if it does, and feel free to try it out, then fallback to make. There are plenty of sharp rocks for beginners, and ironically the existing make-based build system is probably one of them. (Having said that, it’s very helpful to know the stages of compilation, so hopefully whatever docs we arrive at will point the beginner to something explaining what’s going on as they do their first bootstrapping build, for the curious.

Actually, after talking to both the Simons as well as Alp, one of the core people in the Hadrian project (if not the mastermind), we tentatively decided to write the Newcomers' Guide for Hadrian, not Make. In principle, Hadrian should be able to do everything that is needed for this, and the "regular" code paths have been tested extensively, and as you have noticed, it is a lot more user friendly. We may still want to link to the Make-based build instructions somewhere, but present Hadrian as the default option.

A short explanation of build stages will of course still be in the Guide - they are just as relevant to Hadrian as they are to the Make build system. However, the tutorial is quite long as it is already, so I want to keep it as short as possible, delegating in-depth explanations to other (ideally existing) wiki pages.

If you like, you can follow along with my progress:

https://github.com/tdammers/ghc-wiki/blob/wip/newcomers/newcomers-tutorial.m...

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Tobias Dammers

10:10 a.m.

On Wed, Jan 30, 2019 at 03:01:24PM +0000, Matthew Pickering wrote:

...

Whilst we're at it, is there any consensus to make the default build settings more friendly to developers?

The default is still perf which takes a very long time. devel2 would be an appropriate choice I think for newcomers.

The way I wrote it right now is that for the very first build, you use whatever default GHC ships with, just to make sure you succeed in making a clean build on a pristine checkout. After that, I do recommend using the "devel2" flavour. I do believe that release build settings should be the default though, simply because of the "install from source" use case. Aspiring GHC hackers will have to learn how to configure the build anyway, might as well teach them right away.

Ben Gamari

8:40 p.m.

Tobias Dammers writes:

...

On Wed, Jan 30, 2019 at 03:01:24PM +0000, Matthew Pickering wrote:

...
Whilst we're at it, is there any consensus to make the default build settings more friendly to developers?

The default is still perf which takes a very long time. devel2 would be an appropriate choice I think for newcomers.

The way I wrote it right now is that for the very first build, you use whatever default GHC ships with, just to make sure you succeed in making a clean build on a pristine checkout. After that, I do recommend using the "devel2" flavour.

I do believe that release build settings should be the default though, simply because of the "install from source" use case. Aspiring GHC hackers will have to learn how to configure the build anyway, might as well teach them right away.

Agreed. The default in a clean checkout should remain perf. However, it would be reasonable for the newcomers instructions to start off with devel2. For most contributors working in compiler/ this is the right default. Cheers, - Ben

Tobias Dammers

31 Jan 31 Jan

10:48 a.m.

One more thing I noticed: the current Newcomers instructions say to clone git://github.com/ghc/ghc, but if you're going to use the gitlab-based MR workflow later on, cloning the gitlab repo directly is going to be a lot more convenient. And then there's also git.haskell.org, which is what I've been using so far. So which one of these should we tell people to clone? I'm inclined to recommend the following workflow: 1. Create gitlab account as needed 2. Fork the GHC project 3. Clone your fork from gitlab 4. Create feature branch 5. Make changes, squash, validate, rebase, push to fork 6. Create MR on gitlab This would keep the hassle to a minimum for a new contributor, and does not require push permissions on `ghc/ghc`. On Sat, Jan 19, 2019 at 03:55:06PM -0500, Ben Gamari wrote:

...

For those following along at home:

David has been looking at revising our contributor documentation. He has started consolidating a variety of relevant content on the Contributing page of the Wiki [1]. Below are my thoughts; feel free to chime in with your own.

David,

The contributing page is looking quite good. However, I do wonder whether we could reduce the link "fan-out" a bit more: it still rather feels like a collection of links with no clear "beginning".

The "Newcomers to GHC" section is a great start but I see two potential issues:

* we don't clearly articulate the precise steps that a newcomer will need to take

* the first thing we mention are four links which, while useful, constitute a significant volume of reading for a newcomer. I fear we may lose people at this point.

Regarding the second point, I think that WorkingConventions/FixingBugs is a good model in that it clearly lists a series of concrete steps that the contributor should take. Admittedly, I think some of the detail should be dropped or moved (e.g. the mention of setting git's user.name variable is likely unnecessary in 2019).

I think that something similar to this list should be the first thing one sees when they reach the contributing page. Ideally the "typical" case of a new contributor wanting to submit their first patch would be able to gather everything they need to get started in one or two screenfuls of text. After that prose can come additional links to more in-depth documentation.

Other various issues I noticed:

* We link to wiki:WorkingConventions from a variety of places (including wiki:Contributing) but it is now just a link to wiki:Contributing.

* wiki:WorkingConventions/FixingBugs still has references to Phabricator. In general we should start culling such references.

* wiki:WorkingConventions/FixingBugs also has references to Trac documentation. We should try to replace these with the relevant GitLab documentation when we migrate.

* wiki:WorkingConventions/FixingBugs should be updated to reflect that GitLab CI is now the source of truth for validation.

* I don't know exactly how this should look but I think we need to do a better job of concisely stating what we expect of contributions. That is:

* commit messages should be readable and discuss what the patch does. "Fixes #NNNN" is not an adequate commit message.

* changes should be commented where necessary (my usual rule of thumb is "write the comment you would have liked to read when you started writing your patch"). We should mention the Note convention.

* commit messages and comments should refer to ticket numbers where appropriate (e.g. using usual #NNNN syntax; people often get this wrong).

* commits should be either squashed or logically distinct, individually buildable changes.

* changes to most of `base` need to go through the CLC (this may be optional as defining what set of `base` this applies to is a bit tricky; in the interest of keeping things concise we may be better off handling this personally on a case-by-case basis)

* code changes should conform to GHC's (somewhat fluid, for better or worse) code style (https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle)

* thought should be given to testing

Having a document which succinctly summarised these expectations as we could easily refer to it during code review. Even better, we could excerpt it as a checklist in our merge request description template (I have put up an initial attempt at this as !149).

Anyways, there is more to be said here but this email is getting a bit long so let's leave it for future discussions.

Cheers,

- Ben

[1] https://ghc.haskell.org/trac/ghc/wiki/Contributing

...

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

-- Tobias Dammers - tdammers@gmail.com

Matthew Pickering

10:57 a.m.

I think you should suggest cloning the main ghc repo and adding the fork as a remote. This is the usual github workflow. On Thu, Jan 31, 2019 at 3:48 PM Tobias Dammers wrote:

...

One more thing I noticed: the current Newcomers instructions say to clone git://github.com/ghc/ghc, but if you're going to use the gitlab-based MR workflow later on, cloning the gitlab repo directly is going to be a lot more convenient. And then there's also git.haskell.org, which is what I've been using so far.

So which one of these should we tell people to clone? I'm inclined to recommend the following workflow:

1. Create gitlab account as needed 2. Fork the GHC project 3. Clone your fork from gitlab 4. Create feature branch 5. Make changes, squash, validate, rebase, push to fork 6. Create MR on gitlab

This would keep the hassle to a minimum for a new contributor, and does not require push permissions on `ghc/ghc`.

On Sat, Jan 19, 2019 at 03:55:06PM -0500, Ben Gamari wrote:

...
For those following along at home:

David has been looking at revising our contributor documentation. He has started consolidating a variety of relevant content on the Contributing page of the Wiki [1]. Below are my thoughts; feel free to chime in with your own.

David,

The contributing page is looking quite good. However, I do wonder whether we could reduce the link "fan-out" a bit more: it still rather feels like a collection of links with no clear "beginning".

The "Newcomers to GHC" section is a great start but I see two potential issues:

* we don't clearly articulate the precise steps that a newcomer will need to take

* the first thing we mention are four links which, while useful, constitute a significant volume of reading for a newcomer. I fear we may lose people at this point.

Regarding the second point, I think that WorkingConventions/FixingBugs is a good model in that it clearly lists a series of concrete steps that the contributor should take. Admittedly, I think some of the detail should be dropped or moved (e.g. the mention of setting git's user.name variable is likely unnecessary in 2019).

I think that something similar to this list should be the first thing one sees when they reach the contributing page. Ideally the "typical" case of a new contributor wanting to submit their first patch would be able to gather everything they need to get started in one or two screenfuls of text. After that prose can come additional links to more in-depth documentation.

Other various issues I noticed:

* We link to wiki:WorkingConventions from a variety of places (including wiki:Contributing) but it is now just a link to wiki:Contributing.

* wiki:WorkingConventions/FixingBugs still has references to Phabricator. In general we should start culling such references.

* wiki:WorkingConventions/FixingBugs also has references to Trac documentation. We should try to replace these with the relevant GitLab documentation when we migrate.

* wiki:WorkingConventions/FixingBugs should be updated to reflect that GitLab CI is now the source of truth for validation.

* I don't know exactly how this should look but I think we need to do a better job of concisely stating what we expect of contributions. That is:

* commit messages should be readable and discuss what the patch does. "Fixes #NNNN" is not an adequate commit message.

* changes should be commented where necessary (my usual rule of thumb is "write the comment you would have liked to read when you started writing your patch"). We should mention the Note convention.

* commit messages and comments should refer to ticket numbers where appropriate (e.g. using usual #NNNN syntax; people often get this wrong).

* commits should be either squashed or logically distinct, individually buildable changes.

* changes to most of `base` need to go through the CLC (this may be optional as defining what set of `base` this applies to is a bit tricky; in the interest of keeping things concise we may be better off handling this personally on a case-by-case basis)

* code changes should conform to GHC's (somewhat fluid, for better or worse) code style (https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle)

* thought should be given to testing

Having a document which succinctly summarised these expectations as we could easily refer to it during code review. Even better, we could excerpt it as a checklist in our merge request description template (I have put up an initial attempt at this as !149).

Anyways, there is more to be said here but this email is getting a bit long so let's leave it for future discussions.

Cheers,

- Ben

[1] https://ghc.haskell.org/trac/ghc/wiki/Contributing

...
_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

-- Tobias Dammers - tdammers@gmail.com _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Tobias Dammers

11:04 a.m.

On Thu, Jan 31, 2019 at 03:57:20PM +0000, Matthew Pickering wrote:

...

I think you should suggest cloning the main ghc repo and adding the fork as a remote. This is the usual github workflow.

And by "the main ghc repo", I take it you mean the gitlab one?

...

On Thu, Jan 31, 2019 at 3:48 PM Tobias Dammers wrote:

...
One more thing I noticed: the current Newcomers instructions say to clone git://github.com/ghc/ghc, but if you're going to use the gitlab-based MR workflow later on, cloning the gitlab repo directly is going to be a lot more convenient. And then there's also git.haskell.org, which is what I've been using so far.

So which one of these should we tell people to clone? I'm inclined to recommend the following workflow:

1. Create gitlab account as needed 2. Fork the GHC project 3. Clone your fork from gitlab 4. Create feature branch 5. Make changes, squash, validate, rebase, push to fork 6. Create MR on gitlab

This would keep the hassle to a minimum for a new contributor, and does not require push permissions on `ghc/ghc`.

On Sat, Jan 19, 2019 at 03:55:06PM -0500, Ben Gamari wrote:

...
For those following along at home:

David has been looking at revising our contributor documentation. He has started consolidating a variety of relevant content on the Contributing page of the Wiki [1]. Below are my thoughts; feel free to chime in with your own.

David,

The contributing page is looking quite good. However, I do wonder whether we could reduce the link "fan-out" a bit more: it still rather feels like a collection of links with no clear "beginning".

The "Newcomers to GHC" section is a great start but I see two potential issues:

* we don't clearly articulate the precise steps that a newcomer will need to take

* the first thing we mention are four links which, while useful, constitute a significant volume of reading for a newcomer. I fear we may lose people at this point.

Regarding the second point, I think that WorkingConventions/FixingBugs is a good model in that it clearly lists a series of concrete steps that the contributor should take. Admittedly, I think some of the detail should be dropped or moved (e.g. the mention of setting git's user.name variable is likely unnecessary in 2019).

I think that something similar to this list should be the first thing one sees when they reach the contributing page. Ideally the "typical" case of a new contributor wanting to submit their first patch would be able to gather everything they need to get started in one or two screenfuls of text. After that prose can come additional links to more in-depth documentation.

Other various issues I noticed:

* We link to wiki:WorkingConventions from a variety of places (including wiki:Contributing) but it is now just a link to wiki:Contributing.

* wiki:WorkingConventions/FixingBugs still has references to Phabricator. In general we should start culling such references.

* wiki:WorkingConventions/FixingBugs also has references to Trac documentation. We should try to replace these with the relevant GitLab documentation when we migrate.

* wiki:WorkingConventions/FixingBugs should be updated to reflect that GitLab CI is now the source of truth for validation.

* I don't know exactly how this should look but I think we need to do a better job of concisely stating what we expect of contributions. That is:

* commit messages should be readable and discuss what the patch does. "Fixes #NNNN" is not an adequate commit message.

* changes should be commented where necessary (my usual rule of thumb is "write the comment you would have liked to read when you started writing your patch"). We should mention the Note convention.

* commit messages and comments should refer to ticket numbers where appropriate (e.g. using usual #NNNN syntax; people often get this wrong).

* commits should be either squashed or logically distinct, individually buildable changes.

* changes to most of `base` need to go through the CLC (this may be optional as defining what set of `base` this applies to is a bit tricky; in the interest of keeping things concise we may be better off handling this personally on a case-by-case basis)

* code changes should conform to GHC's (somewhat fluid, for better or worse) code style (https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle)

* thought should be given to testing

Having a document which succinctly summarised these expectations as we could easily refer to it during code review. Even better, we could excerpt it as a checklist in our merge request description template (I have put up an initial attempt at this as !149).

Anyways, there is more to be said here but this email is getting a bit long so let's leave it for future discussions.

Cheers,

- Ben

[1] https://ghc.haskell.org/trac/ghc/wiki/Contributing

...
_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

-- Tobias Dammers - tdammers@gmail.com _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

-- Tobias Dammers - tdammers@gmail.com

Matthew Pickering

11:22 a.m.

Yes, clone from https://gitlab.haskell.org/ghc/ghc.git Then submodules will work out properly as well. Matt On Thu, Jan 31, 2019 at 4:05 PM Tobias Dammers wrote:

...

On Thu, Jan 31, 2019 at 03:57:20PM +0000, Matthew Pickering wrote:

...
I think you should suggest cloning the main ghc repo and adding the fork as a remote. This is the usual github workflow.

And by "the main ghc repo", I take it you mean the gitlab one?

...
On Thu, Jan 31, 2019 at 3:48 PM Tobias Dammers wrote:

...
One more thing I noticed: the current Newcomers instructions say to clone git://github.com/ghc/ghc, but if you're going to use the gitlab-based MR workflow later on, cloning the gitlab repo directly is going to be a lot more convenient. And then there's also git.haskell.org, which is what I've been using so far.

So which one of these should we tell people to clone? I'm inclined to recommend the following workflow:

1. Create gitlab account as needed 2. Fork the GHC project 3. Clone your fork from gitlab 4. Create feature branch 5. Make changes, squash, validate, rebase, push to fork 6. Create MR on gitlab

This would keep the hassle to a minimum for a new contributor, and does not require push permissions on `ghc/ghc`.

On Sat, Jan 19, 2019 at 03:55:06PM -0500, Ben Gamari wrote:

...
For those following along at home:

David has been looking at revising our contributor documentation. He has started consolidating a variety of relevant content on the Contributing page of the Wiki [1]. Below are my thoughts; feel free to chime in with your own.

David,

The contributing page is looking quite good. However, I do wonder whether we could reduce the link "fan-out" a bit more: it still rather feels like a collection of links with no clear "beginning".

The "Newcomers to GHC" section is a great start but I see two potential issues:

* we don't clearly articulate the precise steps that a newcomer will need to take

* the first thing we mention are four links which, while useful, constitute a significant volume of reading for a newcomer. I fear we may lose people at this point.

Regarding the second point, I think that WorkingConventions/FixingBugs is a good model in that it clearly lists a series of concrete steps that the contributor should take. Admittedly, I think some of the detail should be dropped or moved (e.g. the mention of setting git's user.name variable is likely unnecessary in 2019).

I think that something similar to this list should be the first thing one sees when they reach the contributing page. Ideally the "typical" case of a new contributor wanting to submit their first patch would be able to gather everything they need to get started in one or two screenfuls of text. After that prose can come additional links to more in-depth documentation.

Other various issues I noticed:

* We link to wiki:WorkingConventions from a variety of places (including wiki:Contributing) but it is now just a link to wiki:Contributing.

* wiki:WorkingConventions/FixingBugs still has references to Phabricator. In general we should start culling such references.

* wiki:WorkingConventions/FixingBugs also has references to Trac documentation. We should try to replace these with the relevant GitLab documentation when we migrate.

* wiki:WorkingConventions/FixingBugs should be updated to reflect that GitLab CI is now the source of truth for validation.

* I don't know exactly how this should look but I think we need to do a better job of concisely stating what we expect of contributions. That is:

* commit messages should be readable and discuss what the patch does. "Fixes #NNNN" is not an adequate commit message.

* changes should be commented where necessary (my usual rule of thumb is "write the comment you would have liked to read when you started writing your patch"). We should mention the Note convention.

* commit messages and comments should refer to ticket numbers where appropriate (e.g. using usual #NNNN syntax; people often get this wrong).

* commits should be either squashed or logically distinct, individually buildable changes.

* changes to most of `base` need to go through the CLC (this may be optional as defining what set of `base` this applies to is a bit tricky; in the interest of keeping things concise we may be better off handling this personally on a case-by-case basis)

* code changes should conform to GHC's (somewhat fluid, for better or worse) code style (https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle)

* thought should be given to testing

Having a document which succinctly summarised these expectations as we could easily refer to it during code review. Even better, we could excerpt it as a checklist in our merge request description template (I have put up an initial attempt at this as !149).

Anyways, there is more to be said here but this email is getting a bit long so let's leave it for future discussions.

Cheers,

- Ben

[1] https://ghc.haskell.org/trac/ghc/wiki/Contributing

...
_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

-- Tobias Dammers - tdammers@gmail.com _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

-- Tobias Dammers - tdammers@gmail.com _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

2301

Age (days ago)

2313

Last active (days ago)

List overview

Download

13 comments

5 participants

participants (5)

Ben Gamari
Ben Gamari
Julian Leviston
Matthew Pickering
Tobias Dammers

Thoughts on the Contributing page

tags

participants (5)