Request: Phab Differentials should include road maps

[Simon Peyton Jones]

I frequently find myself asking for a different kind of road map: a wiki page saying
- what is the problem we are trying to solve
- what is the general approach for solving it
- what is the specification for what a GHC user (or maybe a GHC API client,
  depending) would see?
- what is a road map for how the implementation is structured.

We often have these wiki pages but not always.  Simply reviewing a big blob of source-code diffs and trying to reconstruct the above four points is not much fun!  Moreover the act of writing them can be fantastically illuminating.  The StaticPtr stuff is a case in point.

Simon

|  -----Original Message-----
|  From: ghc-devs [mailto:ghc-devs-bounces at haskell.org] On Behalf Of
|  Richard Eisenberg
|  Sent: 14 October 2014 14:34
|  To: ghc-devs at haskell.org Devs
|  Subject: Request: Phab Differentials should include road maps
|  
|  Hi devs,
|  
|  I have what I hope is a simple request: that patch submissions contain
|  a "road map" describing the patch. I'll illustrate via example: I just
|  took a quick look at D323, about updating the design of Uniques.
|  Although this patch was fairly straightforward, I would have been
|  helped by a comment somewhere saying "All the important changes are in
|  Unique.lhs. The rest of the changes are simply propagating the new
|  UniqueDomain type." Then, I would just look at the one file and skim
|  the rest very briefly. The reason I'm requesting this comment from the
|  patch author is that my assumption above -- that all the action is in
|  Unique.lhs -- might be quite wrong. Maybe there's a really important
|  (perhaps one-line) change elsewhere that deserves attention. Or, maybe
|  there's a function/type in Unique.lhs that the patch author is  very
|  uncertain about and wants extra scrutiny. In any case, a few sentences
|  at the top of the patch would help focus reviewers' time where the
|  author thinks it is most neede  d.
|  
|  What do we think? Is this a behavior we wish to adopt?
|  
|  Thanks!
|  Richard
|  _______________________________________________
|  ghc-devs mailing list
|  ghc-devs at haskell.org
|  http://www.haskell.org/mailman/listinfo/ghc-devs