Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
On 6/7/11, James Cook mo...@deepbondi.net wrote: [...] 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). What is the way to indicate actual code stability? Some packages on Hackage definitely have broken parts. Tom ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
On Jun 8, 2011, at 11:08 AM, Tom Murphy wrote: On 6/7/11, James Cook mo...@deepbondi.net wrote: [...] 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). What is the way to indicate actual code stability? Some packages on Hackage definitely have broken parts. Since all cabal fields are set before uploading that would imply someone is uploading something they know to be broken, which doesn't seem right. But assuming some legitimate reason exists, WARNING or DEPRECATED pragmas on the bad stuff would probably be a good way to go. -- James ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
Chris Smith cdsm...@gmail.com 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. I don't think that's a proper rationale to remove the feature, because every feature can be used in a wrong way. It appears to be quite natural to me that people forget to update their module headers, but there are also programmers, who manage their comments very responsibly, including the module header. Personally I used to use the feature, but at some point I abandoned it, because although I always update the comments associated with definitions, I tend to forget the module's head comment. Also since my modules are mostly very related, the stability is a package property for me rather than a module property. If you are serious about removing failed experiments, there are more important places to get started at. ;) Greets, Ertugrul -- nightmare = unsafePerformIO (getWrongWife = sex) http://ertes.de/ ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
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). -- James ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
Hi, James Cook wrote: 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). On http://hackage.haskell.org/packages/archive/base/latest/doc/html/Control-Applicative.html, in the upper right corner, the module is marked as experimental. I think this is a Haddock feature, not a Hackage feature. Tillmann ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
On Jun 7, 2011, at 9:22 AM, Tillmann Rendel wrote: Hi, James Cook wrote: 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). On http://hackage.haskell.org/packages/archive/base/latest/doc/html/Control-Applicative.html , in the upper right corner, the module is marked as experimental. I think this is a Haddock feature, not a Hackage feature. Ah, I did not realize it did that. Looking at the source I see that it is indeed in a haddock comment. In that case, I'll go back and respond to the original question. I do not know why it's labeled experimental, but would hazard a wild guess that it's because the relation of Applicative to Monad is still an open question. -- James ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
On Tue, Jun 7, 2011 at 9:22 AM, Tillmann Rendel ren...@informatik.uni-marburg.de wrote: On http://hackage.haskell.org/packages/archive/base/latest/doc/html/Control-Applicative.html, in the upper right corner, the module is marked as experimental. I think this is a Haddock feature, not a Hackage feature. Oddly, I couldn't find any of the fields in the haddock module header documented anywhere, though I didn't perform a very thorough search. I also observe that, in base, Data.Bool is apparently experimental, whereas Control.Monad is merely provisional. Prelude, at least, is reassuringly stable. - C. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
On Tue, Jun 7, 2011 at 3:05 PM, James Cook mo...@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@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe -- Work is punishment for failing to procrastinate effectively. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
On 7 June 2011 15:05, James Cook mo...@deepbondi.net wrote: 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. I think no one really updates this field and it's a human factor that could otherwise be generated by Hackage reliably. I'm using many packages that are experimental or unstable that've been stable for a year or more. The field is mostly useless to me. The stability of a package can be judged based on how often the versions bump up based on the PVP and/or the exports of the package change, that is something Hackage could trivially do. Agreed, the naming is also ambiguous, “API stability” seems more straight-forward. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
On Jun 7, 2011, at 10:17 AM, Christopher Done wrote: On 7 June 2011 15:05, James Cook mo...@deepbondi.net wrote: 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. I think no one really updates this field and it's a human factor that could otherwise be generated by Hackage reliably. I'm using many packages that are experimental or unstable that've been stable for a year or more. The field is mostly useless to me. The stability of a package can be judged based on how often the versions bump up based on the PVP and/or the exports of the package change, that is something Hackage could trivially do. Agreed, the naming is also ambiguous, “API stability” seems more straight-forward. I can't speak for anyone besides myself, but I do update it and its value is determined, for me, in a way that could never be automated. When I mark a package provisional or experimental, I am saying that I am not convinced that the API I've created is the best one I can come up with, and often I have specific plans to (when I get around to it) change it. It is an indication of intent for, not history of, change. Similarly, when I do reach a design that I'm satisfied with, I change the stability field. But an automated decision system has no conceivable way of knowing that the major change I just made will be the last major change. -- James ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
I like the goal of the stability field, but I don't know how to use it. Is it intended to track a package's overall maturity ? Eg: experimental - alpha - beta - almost ready - stable - mature - obsolete Or, since many packages have multiple major and minor releases, to track the current release status ? Eg: experimental - alpha - beta - stable - alpha - beta - ... Currently, I expect every package author follows their own wording and usage, or ignores it, so it's hard to rely on. So good idea to discuss it. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Proposal: remove Stability from haddock documentation on hackage
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. -- Chris Smith ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
