Process proposal: Require explicit user-oriented timelines in library proposals

[Ben Gamari]

tl;dr. I think proposals should include a user-oriented timeline,
       e.g. [2]

Hello everyone,

Recently I've been doing some thinking about library change roadmap and
in particular our process for considering changes. While this process
has without question improved remarkably in the last few years, I think
there is still some room for improvement in communicating future plans,
in particular to users.

From the user's perspective there are three important points in time
(let's call them milestones) associated with a library proposal (using
MonadFail as an example),

 A. When can I start asking for warnings?

    This is the time when we add warnings notifying users of the coming
    change to -Wcompat (e.g. this is 8.0 in the case of MonadFail)

 B. When can I start conveniently acting upon these warnings?

    This is the point where enough time has passed that the user can take
    action on the warning in a manner consistent with the three-release
    policy (e.g. 8.4 in the case of MonadFail?)

    Ideally proposals would also include concrete examples of the sort of
    refactoring that would typically be necessary.
   
 C. For how long can I procrastinate?

    This is the point where the user's code will break if they have not
    taken action (e.g. 8.6 in the case of MonadFail?)

In the case of the proposals currently on the roadmap [1] it can
sometimes be rather tricky to determine exactly where each of these points
fall as the proposals tend to discuss implementation and leave the
implications on the user implicit.

I propose that we require that formal proposals lay out a user-oriented
timeline explicitly. I have adapted the Semigroup-Monoid proposal [2] to
demonstrate what this might look like.

Of course, the timeline is a simplification of reality: In some cases,
there may be multiple times associated with each milestone. For
instance, in the case of the Semigroup-Monoid proposal it would seem
that there are two point Cs,

  * Things break once in Phase 2b since the user must provide Semigroup
    instances to go along with their Monoid instances

  * Things break again in Phase 4 since the user must remove mappend
    definitions from the Monoid instances

This should be made explicit in the timeline [3].

How does this sound?

Cheers,

- Ben


[1] https://prime.haskell.org/wiki/Libraries/Proposals
[2] https://ghc.haskell.org/trac/ghc/wiki/BenGamari/ProposalMilestoneExample#MigrationPlan

[3] Although arguably this proposal should be two distinct pieces:

      * Add Semigroup as a superclass of Monoid

      * Remove mappend from Monoid

    If the Semigroup-Monoid proposal were so divided it would break down
    quite cleanly on the timeline proposed above.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 472 bytes
Desc: not available
URL: <http://mail.haskell.org/pipermail/libraries/attachments/20160213/ddad1a61/attachment.sig>