3

Let us say that I have worked on a haskell library and am now ready to release a beta version of the software to hackage/make repo public on github etc.

Possible Solutions and why they do not work for me
  1. Use packagename-0.0.0.1-alpha or similar.
    The problem here is quite simple: The Haskell PVP Specification does not allow it: (bold is me)

The components of the version number MUST be numbers! Historically Cabal supported version numbers with string tags at the end, e.g. 1.0-beta This proved not to work well because the ordering for tags was not well defined. Version tags are no longer supported and mostly ignored, however some tools will fail in some circumstances if they encounter them.

  1. Just use packagename-0.* until it is out of alpha/beta (and then use packagename-1.*).
    The problem here is twofold:
    1. This method would not work for describing relase candidates which are post version 1.
    2. Programmers from other ecosystems, such as that of rust, where it is quite common to have a stable library in 0.*, might wrongly assume that this library is stable. (Of course, it could be mitigated somewhat with a warning in the README, but I would prefer a better solution still.)

So, what is the best (and most conventional in haskell) way to indicate that the library version is in alpha/beta stage of development or is a release candidate?

Naitik Mundra
  • 418
  • 3
  • 14
  • 1
    You don't need to invoke other language ecosystems for the idea that `0.*` releases are not necessarily unstable. Old, core, packages like `bytestring` do this in Haskell. The first digit is mostly a "marketing number"; whatever it communicates is up to individual packages. You can use it for "0 = unstable" if you want, but people would have to read your docs to find that out. – Ben Dec 21 '22 at 06:27
  • 1
    I think if it's on Hackage, it's "released", not a "release candidate". The "production readiness" of the package is more than can be encoded in a version number (would you blindly trust a package just because its version isn't tagged as RC?). I don't see anything wrong with just releasing `1.4.0` and documenting it as not fully stable, and then releasing `1.4.0.1` later and documenting that as the minimum version to use for the `1.4.0` series. You have to trust that if people care about only using production ready software they're going to review your docs to find out whether it is. – Ben Dec 21 '22 at 06:35
  • @Ben Thank you for your comments. As for your second comment, my question was admittedly, poorly phrased. My intention was to find out a convention across github/forums/reddit/hackage etc. Also, while vetting is an obvious part of using a library, it is easy to eliminate, sometimes, a library marked alpha/beta for industry/commercial solutions of for example. As for now, I have decided to simply use the `0.*` version combined with @Daniel Wagner's answer because that seems to be the best solution. – Naitik Mundra Dec 21 '22 at 16:37

1 Answers1

2

As far as I know, there is not a package-wide way to say this. However, you can add a module description that describes the stability of the module to each of your modules' documentation.

{-|
Stability: experimental
-}
module PackageName.ModuleName where
Daniel Wagner
  • 145,880
  • 9
  • 220
  • 380
  • Do you know of the way **most** packages do it? (if they do it at all)? Also, would this be visible on hackage, without reading the README? – Naitik Mundra Dec 20 '22 at 15:21
  • 3
    Most packages don't do it. Of the packages that do it, this is the way most packages do it. It is visible on Hackage without reading the README, but you must look at the documentation of one of the modules; it is not visible on the package overview page. – Daniel Wagner Dec 20 '22 at 15:23