Thoughts on the Contributing page

[Ben Gamari]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 487 bytes
Desc: not available
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20190119/16fba6f5/attachment.sig>