[Haskell-cafe] Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Tue Dec 16 17:31:05 UTC 2014

Thanks everyone for your feedback!

>From what I'm hearing it sounds like in the scheme "A.B.C.D" is roughly
handled like this: (I know "D" isn't technically in the PVP)

* If the change includes a major overhaul to the design of the package, A
should be bumped. Things like all modules changed, introducing a new monad
that should be used instead, etc.

* If the change includes non-backwards compatible features that lives
inside the existing design, only B should be bumped. Things like
refactoring existing functions, changing the signature and/or introducing
new data types for existing functions.

* If the change includes backwards compatible changes, only C should be
bumped. Things like adding a new convenience function. Adding brand new
functions/modules that didn't have any existing counterpart.

* (Unspoken, but many people do it) If the change includes a minor
backwards compatible fix, D should be bumped. A typo in a string, a
security patch that doesn't change the signature or typical behavior.

Changing the package's dependencies also feels like it could either end up
bumping B if you're changing the minimum requirements of existing
dependencies, or C if you introduce a new dependency.

Obviously some package maintainers will deviate from above. However, if
I've summarized the typical community process, could we add these examples
(or a variation of them) to
https://www.haskell.org/haskellwiki/Package_versioning_policy ? As a
newcommer, this would have helped me out to understand how people version
packages and to have some idea of interpreting the version history on
hackage pages. If there's not too much objection to that inclusion, is
there a way I can help aid that wiki change process?

Tobias wrote:

>   When you introduce a new entity in the public interface, such as a new
>   typeclass, a new exported type, a new exported function, etc., you
>   should bump the *second* number. This is because such introductions
>   are only breaking changes when the consumer imports your modules
>   unqualified and completely (i.e. `import The.Module`, not `import
>   qualified The.Module as TM` nor `import The.Module (foo, bar)`).
>   Importing your module "safely" will not break anything because the
>   previous entities are still there, and the new ones simply won't be
>   imported, so they cannot cause any clashes.

If you ignore the case of orphan instances, from what I read of the PVP
<https://www.haskell.org/haskellwiki/Package_versioning_policy> this is
very loosely interpreting the phrase "*A.B* may remain the same...". I
would honestly expect C to be bumped in this scenario instead because what
you describe sounds like a backwards compatible addition. In fact it gets a
little more odd since the same sentence says "...the new *C* must be
greater than the old *C". *Bumping **both** B and C feels odd to me.

Roman wrote:

> We saw something similar with text, people got angry. If a library becomes
> popular before it reaches 1.0, it probably never will.

Johan wrote:

> Lots of really stable Haskell libraries (e.g. containers) are still on
> version 0.X.

Vincent wrote:

> Text is one of canonical example when it was bumped to 1.x recently and
> lots of people complained that it wasn't the right thing to do.
>

Corentin wrote:

> Anyway the fact that we like to have "V1.0" to mean "work done" is more a
> question of aesthetic.

I know upper bound constraints is a contentious topic in the Haskell
community. I was trying to avoid bringing that up altogether for these
questions. Setting aside the common "at what point do the maintainer(s)
commit to the existing API and mark the big 1 point 0" dilemma, very stable
0.x packages are one of the reasons why I was confused and asked the list.

It feels like the PVP encourages packages to not ever go 1.0 since bumping
B (0.1, 0.2) are considered major versions, and therefore packages can
continue their stable maintenance ignoring A forever (excluding major
overhauls discussed above of course). In my opinion, that is confusing
behavior and should not be encouraged. It's a bummer to me to hear that
people got upset when Text went from 0.11 to 1.0.

Does anyone have any links to the threads where people were upset because
of the Text 1.0 change? I'd like know if it was just simply because they
had to change the upper bound constraint for many packages or if there was
more to it than that. I found a few emails when it occurred
https://www.haskell.org/pipermail/haskell-cafe/2013-December/111845.html
but nothing beyond that.

-Zach

On Tue, Dec 16, 2014 at 11:00 AM, Felipe Lessa <felipe.lessa at gmail.com>
wrote:
>
> On 16-12-2014 07:18, Tobias Dammers wrote:
> > IIRC, the rules (for libraries at least) are (correct me if I'm wrong):
>
> These are not rules encoded by the PVP.  The PVP doesn't prescribe how A
> or B should be changed besides stating when the major version should be
> bumped.  This can be accomplished by increasing either A or B, but it's
> entirely up to the author to decide which.  Any author is free to use
> whatever rule they see fit.
>
> Cheers,
>
> --
> Felipe.
>
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
>

-- 
-Zach
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20141216/b155c531/attachment.html>