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