Re: [Haskell-cafe] Package documentation complaints -- and a suggestion

On 10/25/11 3:54 AM, Gregory Collins wrote:

On Tue, Oct 25, 2011 at 4:34 AM, wren ng thornton wrote:

...

I'm not so sure about that exemption. The "experimental" stability level seems to be the norm on Hackage and often means "I use this for real projects, but because I use it for real projects I'm not quite willing to hammer the API in stone just yet".

...

Before dealing with automatic documentation requirements, perhaps it'd be better to develop a standard consensus on the terms used in the stability field and actively advocating for people to adopt it, as was done with the PVP.

I think there's no need to cajole people into it -- if Hackage 2 puts "stable" packages on a different / better list, there's your social pressure. Right now the stability flag in the .cabal file, as you pointed out, is almost completely content-free.

The problem isn't social pressure to be stable, it's the ambiguity of what "stable" means. If Hackage 2 institutes a policy whereby things claiming to be stable are treated better, then "stable" is likely to become the new "experimental". Just because I call something stable doesn't mean that it is. Just because I give something enough documentation so appease the bots so that I'm allowed to call it stable doesn't mean that it is. Frankly, giving a one-line synopsis of what a function does isn't a high enough barrier to entry to keep someone from abusing the system in order to self-select which index page they get put on. The only way to get a consensus about what "stable", "experimental", etc mean is ...to get a consensus about what they mean. It's exactly the same thing as the PVP: in order to get people to agree about what version increments mean, we need to get them to agree to mean whatever it is everybody else thinks they mean. Automating the verification of that agreement is a nice tool to have to hand, but it's meaningless without the agreement about what we're all engaged in. -- Live well, ~wren