Thoughts on the Contributing page

[Tobias Dammers]

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 at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


-- 
Tobias Dammers - tdammers at gmail.com