Thoughts on the Contributing page

[Matthew Pickering]

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 <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