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

[Jeffrey Brown]

It sounds like we're trying to shoehorn more information into a single
ordinal value than it can represent. It might be unreasonable to expect to
be able to learn so much from so little.

In my own code, if I want to look back at which changes were small and
which were big, I read the Subversion comments for each revision. I do like
the idea of reducing the text footprint of that information to three or
four numbers -- it would be easier to read fast -- but I have yet to
imagine how.

On Tue, Dec 16, 2014 at 9:31 AM, Zach Moazeni <zach.moazeni at gmail.com>
wrote:
>
> 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
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20141216/b38521eb/attachment.html>