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

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#Mig... [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.

Hi, Am Samstag, den 13.02.2016, 15:11 +0100 schrieb Ben Gamari:
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.
Did you see the example roadmap I created on https://prime.haskell.org/wiki/Libraries/3-Release-Policy That goes a bit in your direction.
How does this sound?
Good! Gruß, Joachim -- Joachim “nomeata” Breitner mail@joachim-breitner.de • https://www.joachim-breitner.de/ XMPP: nomeata@joachim-breitner.de • OpenPGP-Key: 0xF0FBF51F Debian Developer: nomeata@debian.org

Joachim Breitner
Hi,
Am Samstag, den 13.02.2016, 15:11 +0100 schrieb Ben Gamari:
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.
Did you see the example roadmap I created on https://prime.haskell.org/wiki/Libraries/3-Release-Policy
Ahh, indeed I did not. Thanks for the reference. That comes quite close to my example. Would it be possible to bring the active proposals up to this standard? Cheers, - Ben

Everything that the CLC has in the works that affects the Prelude already
has been brought up most of the way to this standard, in that
https://prime.haskell.org/wiki/Libraries/Proposals gives the summary of the
resulting timeline with the outstanding proposals worked out in in a user
facing manner.
It doesn't enumerate the explicit actions the user should take at each step
to build in whatever the 3 release compatible mode would be at any given
point, however. Help on that front would be welcome.
A few details change if the Simons choose to ultimately roll -Wcompat into
-Wall, as the 3 Release Policy takes a bit of a hit, but the general
timeline remains intact.
My primary concern is that if we ask end users who put forth proposals for
excruciating detail that considers everything in the 3 release policy, we
limit ourselves to proposals that come from people already deeply familiar
with the process.
The current mindset is that if we do choose to adopt a proposal once the
community has agreed to the broad strokes, we'll need to do what we can to
raise it to this level and incorporate it into the roadmap.
Currently we're doing so with respect to Prelude-affecting changes, but
spreading this (or something weaker) out to the wider set of core libraries
is something we could consider doing once we get a sense of how well it is
working in practice, and if there is a general sense that the stability it
brings outweighs the rather significant delays it imparts to the process.
Keep in mind we already have plans that stretch out to GHC 8.6 as a
consequence of the 3 Release Policy. Almost all significant changes will
now take around 4 years to play out. Around the Prelude that seems about
right. Around the rest of the core libraries that would likely become a
rather significant pain point.
-Edward
On Sat, Feb 13, 2016 at 4:55 PM, Ben Gamari
Joachim Breitner
writes: Hi,
In the case of the proposals currently on the roadmap [1] it can sometimes be rather tricky to determine exactly where each of these
Am Samstag, den 13.02.2016, 15:11 +0100 schrieb Ben Gamari: points
fall as the proposals tend to discuss implementation and leave the implications on the user implicit.
Did you see the example roadmap I created on https://prime.haskell.org/wiki/Libraries/3-Release-Policy
Ahh, indeed I did not. Thanks for the reference. That comes quite close to my example. Would it be possible to bring the active proposals up to this standard?
Cheers,
- Ben
_______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

Edward Kmett
Everything that the CLC has in the works that affects the Prelude already has been brought up most of the way to this standard, in that https://prime.haskell.org/wiki/Libraries/Proposals gives the summary of the resulting timeline with the outstanding proposals worked out in in a user facing manner.
It doesn't enumerate the explicit actions the user should take at each step to build in whatever the 3 release compatible mode would be at any given point, however. Help on that front would be welcome.
I would love to pitch in however it doesn't seem that users outside of the committee have write access to wiki.
A few details change if the Simons choose to ultimately roll -Wcompat into -Wall, as the 3 Release Policy takes a bit of a hit, but the general timeline remains intact.
Right. However, keep in mind that it's possible that the Three-Release Policy may take a hit even if -Wcompat remains independent due to GHC's stance on -Wall stability.
My primary concern is that if we ask end users who put forth proposals for excruciating detail that considers everything in the 3 release policy, we limit ourselves to proposals that come from people already deeply familiar with the process.
The current mindset is that if we do choose to adopt a proposal once the community has agreed to the broad strokes, we'll need to do what we can to raise it to this level and incorporate it into the roadmap.
Right; I'm not suggesting that a proposal must meet this standard to even be considered. Rather, as you said, I would like if this standard were enforced on proposals by the time they are adopted. Really, my critique is mostly on the presentation of this information. It's possible for a user to determine the implications of a given proposal with what is on the wiki currently, but it's not as easy as it could be.
Currently we're doing so with respect to Prelude-affecting changes, but spreading this (or something weaker) out to the wider set of core libraries is something we could consider doing once we get a sense of how well it is working in practice, and if there is a general sense that the stability it brings outweighs the rather significant delays it imparts to the process.
Keep in mind we already have plans that stretch out to GHC 8.6 as a consequence of the 3 Release Policy. Almost all significant changes will now take around 4 years to play out. Around the Prelude that seems about right. Around the rest of the core libraries that would likely become a rather significant pain point.
Indeed. Cheers, - Ben

On Sun, Feb 14, 2016 at 10:08 AM, Ben Gamari
Edward Kmett
writes: I would love to pitch in however it doesn't seem that users outside of the committee have write access to wiki.
I'm pretty sure that Herbert can set you up with access. I'm more than willing to consent to that here from our side. Right. However, keep in mind that it's possible that the Three-Release
Policy may take a hit even if -Wcompat remains independent due to GHC's stance on -Wall stability.
That does indeed seem to be likely the case. We the committee can't control what GHC chooses to do in this regard. We extended the olive branch of the 3 release policy to those concerned that the rate of change was too high. I can say that from our perspective, having the goal of meeting such a policy has helped a great deal from a planning perspective. It took timelines from something completely arbitrary to something forced into a measured pace. To strain that metaphor, we'll prune branches off that branch as needed to accommodate the pressures on the committee from both sides. I do somewhat fear that if we fold -Wcompat into -Wall that at least pragmatically the 3 release policy will no longer really serve the needs of anyone. Really, my critique is mostly on the presentation of this information.
It's possible for a user to determine the implications of a given proposal with what is on the wiki currently, but it's not as easy as it could be.
Sure. We could definitely use help on the presentation side! -Edward
participants (3)
-
Ben Gamari
-
Edward Kmett
-
Joachim Breitner