Thoughts on the Contributing page

Thu Jan 31 16:04:54 UTC 2019

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 <tdammers at gmail.com> 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 at haskell.org
> > > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
> >
> >
> > --
> > Tobias Dammers - tdammers at gmail.com
> > _______________________________________________
> > ghc-devs mailing list
> > ghc-devs at haskell.org
> > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
> _______________________________________________
> 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