[Haskell-cafe] Proposal: remove "Stability" from haddock documentation on hackage

[Gábor Lehel]

On Tue, Jun 7, 2011 at 3:05 PM, James Cook <mokus at deepbondi.net> wrote:
> On Jun 6, 2011, at 10:57 PM, Chris Smith wrote:
>
>> I got asked a question today about why Control.Applicative is labeled as
>> "experimental" on Hackage.  Perhaps that field is something of a failed
>> experiment, and it remaining there is likely to confuse people.
>>
>> Just a thought... not sure of the best place to mention it.
>>
>
> As far as Control.Applicative, I'm not sure to what package you're
> referring.  That label doesn't apply to modules, it applies to packages, and
> Control.Applicative is a part of the "base" package (which is not labeled
> experimental).
>
> Regarding the Stability field itself, I strongly believe in it.  I like to
> know whether code I'm thinking about using is likely to have 15 new versions
> in the next month or whether its interface is likely to change drastically
> with the next release.  When releasing packages I also like to be able to
> state that it's a work in progress and that I decline to promise forward
> compatibility.  If I release a package labeled "experimental", I don't feel
> nearly as bad making major API changes because any users that might have
> picked it up have had fair warning.  On the other hand, if I've marked it
> "stable" or even "provisional", I know I need to make a stronger effort to
> preserve source-level compatibility.
>
> It's good, in my opinion, to be able to state succinctly in a standardized
> way that, although it does something now, what the code does and how it does
> it are probably going to change in the future.
>
> The name of the field could be better, though.  On first exposure, people
> tend to think "stability: experimental" or "stability: unstable" means the
> package is likely to crash (For those who don't know, it means the API is
> likely to change in future releases).

A straightforward option then would be "API stability".

>
> -- James
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>



-- 
Work is punishment for failing to procrastinate effectively.