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

2011-10-30 Thread Malcolm Wallace
> 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". I'd say, rather than rely on social agreement o

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

2011-10-29 Thread wren ng thornton
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

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

2011-10-25 Thread Ketil Malde
Max Rabkin writes: > This is useful information, but to call it "stability" is not only > misleading, but it also prevents the package from using that field to > indicate whether or not it is stable! Oh, right - I'm not much interested in the stability of a package. What I want to know, is whic

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

2011-10-25 Thread Evan Laforge
On Tue, Oct 25, 2011 at 2:17 AM, Ketil Malde wrote: > Ivan Lazar Miljenovic writes: > >> Right, but first we need to define what all those terms _mean_... and >> it's no good saying your package is "stable" if you change the API in >> a large-scale fashion every release. > > I think there are bet

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

2011-10-25 Thread Ivan Lazar Miljenovic
On 25 October 2011 20:17, Ketil Malde wrote: > Ivan Lazar Miljenovic writes: > >> Right, but first we need to define what all those terms _mean_... and >> it's no good saying your package is "stable" if you change the API in >> a large-scale fashion every release. > > I think there are better cri

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

2011-10-25 Thread Max Rabkin
On Tue, Oct 25, 2011 at 11:17, Ketil Malde wrote: > Ivan Lazar Miljenovic writes: > >> Right, but first we need to define what all those terms _mean_... and >> it's no good saying your package is "stable" if you change the API in >> a large-scale fashion every release. > > I think there are bette

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

2011-10-25 Thread Ketil Malde
Ivan Lazar Miljenovic writes: > Right, but first we need to define what all those terms _mean_... and > it's no good saying your package is "stable" if you change the API in > a large-scale fashion every release. I think there are better criteria to use, like: - do exported definition have Hadd

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

2011-10-25 Thread Ivan Lazar Miljenovic
On 25 October 2011 18:54, 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 rea

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

2011-10-25 Thread Gregory Collins
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

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

2011-10-24 Thread Ivan Lazar Miljenovic
On 25 October 2011 13:34, wren ng thornton wrote: > 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. +1, not to

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

2011-10-24 Thread wren ng thornton
On 10/24/11 12:34 PM, Gregory Collins wrote: Examples could include: "Your package lacks a description", "more than X% of your modules lack toplevel module comments", "fewer than Y% of your toplevel exports have haddock comments", etc... Packages with stability=experimental would probably be exem

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

2011-10-24 Thread Gregory Collins
On Mon, Oct 24, 2011 at 12:55 PM, Ryan Newton wrote: >> Good point. On the other hand, nobody points package authors to the >> Debian documentation (and Debian also has review for newly uploaded >> packages, as far as I know). > > Re: review process -- Perhaps there would be a use for a review pro

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

2011-10-24 Thread Ryan Newton
> > Good point. On the other hand, nobody points package authors to the > Debian documentation (and Debian also has review for newly uploaded > packages, as far as I know). Re: review process -- Perhaps there would be a use for a review process somewhere between haskell-platform and the unwashed

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

2011-10-23 Thread Antti-Juhani Kaijanaho
On Mon, Oct 10, 2011 at 09:06:01AM +0100, Paterson, Ross wrote: > The distinction between synopsis and description is borrowed from the > Debian package format: > > http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions > > The two fields are aimed at different audiences. Not in D

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

2011-10-10 Thread Max Rabkin
On Mon, Oct 10, 2011 at 10:06, Paterson, Ross wrote: > Max Rabkin writes: >> But I also have a concrete suggestion for Hackage: include the package >> synopsis on the package's page. The distinction between synopsis and >> description can be confusing, and sometimes it seems to violate DRY to >> h

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

2011-10-10 Thread Paterson, Ross
Max Rabkin writes: > But I also have a concrete suggestion for Hackage: include the package > synopsis on the package's page. The distinction between synopsis and > description can be confusing, and sometimes it seems to violate DRY to > have the same info in both. You may have missed the header o

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

2011-10-10 Thread Max Rabkin
On Mon, Oct 10, 2011 at 03:17, John Millikin wrote: > The package summary is "Type-safe ADT-database mapping library.", which > gives some idea about what it does. Whence my suggestion to show this on the package's page. Perhaps I shouldn't have hidden that at the bottom -- I meant this as my mai

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

2011-10-09 Thread John Millikin
The package summary is "Type-safe ADT-database mapping library.", which gives some idea about what it does. In my experience, any package that starts its source files with {-# LANGUAGE GADTs, TypeFamilies, ExistentialQuantification, StandaloneDeriving, TypeSynonymInstances, MultiParamTypeCl

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

2011-10-09 Thread Max Rabkin
Hi all Following a link from the Yesod book, I arrived at [1], curious to find out what groundhog was. Once there, I learned... nothing: "This library provides just the general interface and helper functions. You must use a specific backend in order to make this useful." [1] http://hackage.haskel