Thoughts on the Contributing page

Thu Jan 31 16:22:33 UTC 2019

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