Thoughts on the Contributing page
matthewtpickering at gmail.com
Thu Jan 31 15:57:20 UTC 2019
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 . 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
> >  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
More information about the ghc-devs