Thoughts on the Contributing page
ben at well-typed.com
Sat Jan 19 20:55:06 UTC 2019
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.
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
* 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: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
* 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
* commit messages and comments should refer to ticket numbers where
appropriate (e.g. using usual #NNNN syntax; people often get this
* 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
* 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.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 487 bytes
Desc: not available
More information about the ghc-devs