Platform policy question: API compatability in minor releases

[wren ng thornton]

Duncan Coutts wrote:
> On Sun, 2009-05-10 at 01:18 -0400, wren ng thornton wrote:
> > I still think that it would be good to try to have a three stage model 
> > for releases, instead of the two stage model that seems to be assumed. 
> > Adding new packages or destructive API changes strike me as being very 
> > different from compatible API changes (which are, in turn, separate from 
> > big fixes and bundling fixes). I'd like to see these two types of 
> > changes being distinguished in terms of the release schedule.
> 
> I have to say this isn't something I'd thought of. Tell us more. What
> would this look like? Would it be something like eg only one release per
> year is allowed to make breaking changes?


As far as time frames, I think things will need adjusting as we find out 
more about the development cycles of the new projects to be included in 
the platform, but the idea is something in the spirit of my older 
proposal, arguing "why choose":

On a long-term arc (e.g. 6~12 months) the HP would make major releases. 
These releases could include new packages that have been blessed since 
the previous major release, remove packages that have been deprecated 
(heaven forfend), and destructive API changes as discussed in the PVP 
(moving or renaming modules/functions, irreconcilable type signatures, 
ADT changes,...).

On a mid-term arc (e.g. 3~4 months) the HP would make semi-major 
releases. These releases could include compatible API changes as 
discussed in PVP (adding new modules/functions, generalizing type 
signatures (possibly),...). Potentially the addition of newly blessed 
packages could move here, though see the discussion below.

On a short-term arc (e.g. 4~6 weeks) the HP would make minor releases. 
These releases could include bug fixes for the underlying projects, 
fixes to the packaging/cabalization of the projects, fixes to the 
bundling of the HP, etc.

...

One of the nice things about having a three-way split like this is that 
it allows for clearer epoch boundaries in terms of how often different 
kinds of users will want to upgrade. The fast turnaround of minor 
releases ensures that bugs can be fixed in a prompt manner even for 
sites with complex installation setups (e.g. universities). The moderate 
turnaround of semi-major releases ensures that the HP can still track 
development rather closely, without sacrificing synchronization due to 
"hard" API changes. And the slower turnaround for major releases ensures 
there's still a certain level of prominence for these.

It's nice for active developers to have up-to-date libraries so that 
their development can match with the rest of the community (hence 
semi-major releases). However, for an open-source community it's also 
important to have a certain level of ritual and celebration, in order to 
keep involvement vibrant and to add a sense of urgency and milestones to 
an otherwise calm development cycle (hence the major releases). This is 
one of the reasons I think it would be good to have the addition of 
newly blessed packages only at the major releases instead of at the 
semi-major releases; it adds a deadline and a celebration for people 
wanting to get in. Ideally this should be timed to match up with 
Hackathon or other community events, so folks can work hard and get the 
reward soon afterwards, compounding the effects of these events for 
building community ties.

Because Hackage remains along side the HP, I'm not too worried about 
only having yearly major releases. Provided the right kind of 
automation, developers can "pre-release" major versions on Hackage and 
that gives enough time to see how these changes are accepted by the 
community, before integration into the HP. This can help to solidify 
destructive API changes before those changes are accepted into canon, 
which will improve the overall synchronization effect of the HP.

But for blessing new packages, our propaganda needs to be sure to 
present this codevelopment as a positive thing, otherwise a long release 
of 12 months could inspire bitterness or resentment from those who try 
to make it in and narrowly miss the deadline or the quality criteria. 
Shortening to a 6 month major release cycle will mitigate this, though 
it diminishes the ritualism of the yearly release. A cycle of 8~9 months 
seems to be ideal in terms of grudges, though it doesn't match up with 
the calendar (which introduces a number of other problems). An 
alternative solution for the resentment problem may be to have one of 
the semi-major releases dubbed as a "co-major release" which allows 
blessing new packages, but is otherwise restricted as per semi-major 
releases. On the whole, I think the best approach is the simplest 
though: just have someone managing the media spin and working to keep 
people happy, rather than trying to schedule it away.

-- 
Live well,
~wren