[Haskell-cafe] Proposal: remove "Stability" from haddock documentation on hackage
illissius at gmail.com
Tue Jun 7 16:16:30 CEST 2011
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
> 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
Work is punishment for failing to procrastinate effectively.
More information about the Haskell-Cafe