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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Zach Moazeni-2
Hello,

Forgive me if this is a frequently asked question, I've searched the web and can't find an answer. I originally sent this to the Beginners list and someone said this might get more responses here instead.

What is the history that led up to the PVP specifying two values as the major version?

I come from other tools that primarily use http://semver.org/ (or a variant) and I'm confused in what cases I should bump "A" but not "B" (or bump "B" but not "A")?

A concrete example: If I make backwards incompatible changes to a package whose latest version is 1.0.x, should the next version be 2.0.x or 1.1.x? What sorts of things should I consider for choosing 2.0 over 1.1 and vice versa?


Another question, by far most packages I have encountered either lead with a 0 or a 1 for "A". Does that have some bearing on the long term stability that package users should expect in the future?

Finally, if "1.0.x.." is meant to convey a level of long term support, does "B" get rarely used? Since "C" version bumps to include backwards compatible additions, and "D"+ for backwards compatible bug fixes. (I know "D" isn't technically a PVP category, I'm just relating it to the patch version of semver).

Thanks for your help!

-Zach

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

David Thomas
To my mind, bump A if it's a big change that's going to require a lot
of work tracking it; B if it's a small change that can probably be
upgraded to fairly simply.

On Mon, Dec 15, 2014 at 5:42 PM, Zach Moazeni <[hidden email]> wrote:

> Hello,
>
> Forgive me if this is a frequently asked question, I've searched the web and
> can't find an answer. I originally sent this to the Beginners list and
> someone said this might get more responses here instead.
>
> What is the history that led up to the PVP specifying two values as the
> major version?
>
> I come from other tools that primarily use http://semver.org/ (or a variant)
> and I'm confused in what cases I should bump "A" but not "B" (or bump "B"
> but not "A")?
>
> A concrete example: If I make backwards incompatible changes to a package
> whose latest version is 1.0.x, should the next version be 2.0.x or 1.1.x?
> What sorts of things should I consider for choosing 2.0 over 1.1 and vice
> versa?
>
>
> Another question, by far most packages I have encountered either lead with a
> 0 or a 1 for "A". Does that have some bearing on the long term stability
> that package users should expect in the future?
>
> Finally, if "1.0.x.." is meant to convey a level of long term support, does
> "B" get rarely used? Since "C" version bumps to include backwards compatible
> additions, and "D"+ for backwards compatible bug fixes. (I know "D" isn't
> technically a PVP category, I'm just relating it to the patch version of
> semver).
>
> Thanks for your help!
>
> -Zach
>
> _______________________________________________
> Haskell-Cafe mailing list
> [hidden email]
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Brandon Allbery
In reply to this post by Zach Moazeni-2
On Mon, Dec 15, 2014 at 8:42 PM, Zach Moazeni <[hidden email]> wrote:
Forgive me if this is a frequently asked question, I've searched the web and can't find an answer. I originally sent this to the Beginners list and someone said this might get more responses here instead.

What is the history that led up to the PVP
 
specifying two values as the major version?

One clue might be that that is how GHC itself is versioned.

--
brandon s allbery kf8nh                               sine nomine associates
[hidden email]                                  [hidden email]
unix, openafs, kerberos, infrastructure, xmonad        http://sinenomine.net

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Tikhon Jelvis
I think lens[1] is a good example of a package that uses both major numbers effectively. The second number is bumped each time there is a backwards-incompatible change, and the first number is bumped each time there is a *major* organizational change in the library. (It's up to 4 now.)

To me, this approach makes sense because not all breaking changes are the same. Sometimes you just want to tweak a single call for whatever reason (maybe security), and sometimes you want to reogranize the whole package, move around major modules... etc. Putting both kinds of changes behind the same version number seems a bit awkward.


On Mon, Dec 15, 2014 at 5:49 PM, Brandon Allbery <[hidden email]> wrote:
On Mon, Dec 15, 2014 at 8:42 PM, Zach Moazeni <[hidden email]> wrote:
Forgive me if this is a frequently asked question, I've searched the web and can't find an answer. I originally sent this to the Beginners list and someone said this might get more responses here instead.

What is the history that led up to the PVP
 
specifying two values as the major version?

One clue might be that that is how GHC itself is versioned.

--
brandon s allbery kf8nh                               sine nomine associates
[hidden email]                                  [hidden email]
unix, openafs, kerberos, infrastructure, xmonad        http://sinenomine.net

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe


_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Adam Bergmark-2
In reply to this post by Zach Moazeni-2


On Tue, Dec 16, 2014 at 2:42 AM, Zach Moazeni <[hidden email]> wrote:
Hello,

Forgive me if this is a frequently asked question, I've searched the web and can't find an answer. I originally sent this to the Beginners list and someone said this might get more responses here instead.

What is the history that led up to the PVP specifying two values as the major version?

I come from other tools that primarily use http://semver.org/ (or a variant) and I'm confused in what cases I should bump "A" but not "B" (or bump "B" but not "A")?

A concrete example: If I make backwards incompatible changes to a package whose latest version is 1.0.x, should the next version be 2.0.x or 1.1.x? What sorts of things should I consider for choosing 2.0 over 1.1 and vice versa?

 
Both are allowed, it's up to you and there is no explicit rule to decide. Some people seem to be bumping A for big changes, or to signify that the package is now stable.


Another question, by far most packages I have encountered either lead with a 0 or a 1 for "A". Does that have some bearing on the long term stability that package users should expect in the future?

Formally, no. But some people use it like that.
 

Finally, if "1.0.x.." is meant to convey a level of long term support, does "B" get rarely used? Since "C" version bumps to include backwards compatible additions, and "D"+ for backwards compatible bug fixes. (I know "D" isn't technically a PVP category, I'm just relating it to the patch version of semver).

Thanks for your help!

-Zach

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe


_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Tobias Dammers
In reply to this post by Zach Moazeni-2
IIRC, the rules (for libraries at least) are (correct me if I'm wrong):

- 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.
- When you change the signature of an existing public entity, you should
  bump the first number, because this is a potential breaking change
  even with "safe" imports.
- When you remove an existing public entity, or an entire module, or
  rename either, you should also bump the first number, for the same
  reasons.

And then on the consumer side, this means you can decide to either fix
your dependencies to just the first version number and import everything
"safely" (qualified / per identifier), or to fix them to 2-part version
numbers and use "dangerous" imports.

From my experience, however, this is neither watertight nor something
everyone follows religiously, so in practice it isn't all that useful
after all. Part of the problem is probably that there are no tools in
widespread use that would block a release under a "wrong" version
number, although I don't see any reasons why this should be technically
impossible to do.

On Mon, Dec 15, 2014 at 08:42:48PM -0500, Zach Moazeni wrote:

> Hello,
>
> Forgive me if this is a frequently asked question, I've searched the web
> and can't find an answer. I originally sent this to the Beginners list and
> someone said this might get more responses here instead.
>
> What is the history that led up to the PVP
> <https://www.haskell.org/haskellwiki/Package_versioning_policy> specifying
> two values as the major version?
>
> I come from other tools that primarily use http://semver.org/ (or a
> variant) and I'm confused in what cases I should bump "A" but not "B" (or
> bump "B" but not "A")?
>
> A concrete example: If I make backwards incompatible changes to a package
> whose latest version is 1.0.x, should the next version be 2.0.x or 1.1.x?
> What sorts of things should I consider for choosing 2.0 over 1.1 and vice
> versa?
>
>
> Another question, by far most packages I have encountered either lead with
> a 0 or a 1 for "A". Does that have some bearing on the long term stability
> that package users should expect in the future?
>
> Finally, if "1.0.x.." is meant to convey a level of long term support, does
> "B" get rarely used? Since "C" version bumps to include backwards
> compatible additions, and "D"+ for backwards compatible bug fixes. (I know
> "D" isn't technically a PVP category, I'm just relating it to the patch
> version of semver).
>
> Thanks for your help!
>
> -Zach

> _______________________________________________
> Haskell-Cafe mailing list
> [hidden email]
> http://www.haskell.org/mailman/listinfo/haskell-cafe


--
Tobias Dammers - [hidden email] - 070-3457628 - www.twokings.nl
Maandag t/m donderdag van 9.00 tot 17.30
Voor dringende vragen, mail naar [hidden email]
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Johan Tibell-2
In reply to this post by Zach Moazeni-2
Hi!

On Tue, Dec 16, 2014 at 2:42 AM, Zach Moazeni <[hidden email]> wrote:
A concrete example: If I make backwards incompatible changes to a package whose latest version is 1.0.x, should the next version be 2.0.x or 1.1.x? What sorts of things should I consider for choosing 2.0 over 1.1 and vice versa?

Unless you really change the API drastically I recommend bumping the B component.
 
Another question, by far most packages I have encountered either lead with a 0 or a 1 for "A". Does that have some bearing on the long term stability that package users should expect in the future?

This is something that happens a lot in open source, in Haskell or elsewhere. We We programmers are afraid of calling something 1.0, because that somehow means "done", which we never (think we) are. :) Lots of really stable Haskell libraries (e.g. containers) are still on version 0.X.

-- Johan

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Roman Cheplyaka-2
On 16/12/14 12:36, Johan Tibell wrote:

> Hi!
>
> On Tue, Dec 16, 2014 at 2:42 AM, Zach Moazeni <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     A concrete example: If I make backwards incompatible changes to a
>     package whose latest version is 1.0.x, should the next version be
>     2.0.x or 1.1.x? What sorts of things should I consider for choosing
>     2.0 over 1.1 and vice versa?
>
>
> Unless you really change the API drastically I recommend bumping the B
> component.
>  
>
>     Another question, by far most packages I have encountered either
>     lead with a 0 or a 1 for "A". Does that have some bearing on the
>     long term stability that package users should expect in the future?
>
>
> This is something that happens a lot in open source, in Haskell or
> elsewhere. We We programmers are afraid of calling something 1.0,
> because that somehow means "done", which we never (think we) are. :)
> Lots of really stable Haskell libraries (e.g. containers) are still on
> version 0.X.

Upper bounds contribute to this problem, too.

Suppose you've decided that 'containers' is stable enough to be at 1.0.

Now all packages need to be updated, because they most probably depend
on 'containers < 1' or tighter.

We saw something similar with text, people got angry.

If a library becomes popular before it reaches 1.0, it probably never will.

Roman
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Erik Hesselink
On Tue, Dec 16, 2014 at 11:49 AM, Roman Cheplyaka <[hidden email]> wrote:

> On 16/12/14 12:36, Johan Tibell wrote:
>> On Tue, Dec 16, 2014 at 2:42 AM, Zach Moazeni <[hidden email]
>> <mailto:[hidden email]>> wrote:
>>     Another question, by far most packages I have encountered either
>>     lead with a 0 or a 1 for "A". Does that have some bearing on the
>>     long term stability that package users should expect in the future?
>>
>>
>> This is something that happens a lot in open source, in Haskell or
>> elsewhere. We We programmers are afraid of calling something 1.0,
>> because that somehow means "done", which we never (think we) are. :)
>> Lots of really stable Haskell libraries (e.g. containers) are still on
>> version 0.X.
>
> Upper bounds contribute to this problem, too.
>
> Suppose you've decided that 'containers' is stable enough to be at 1.0.
>
> Now all packages need to be updated, because they most probably depend
> on 'containers < 1' or tighter.
>
> We saw something similar with text, people got angry.
>
> If a library becomes popular before it reaches 1.0, it probably never will.

I don't understand this. How is bumping 'A' different from bumping
'B'? You could just bump 'A' (to 1, for example) instead of 'B' when
you make an API breaking change, and it's no extra effort for people
who depend on you.

Erik
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Roman Cheplyaka-2
On 16/12/14 13:00, Erik Hesselink wrote:

> On Tue, Dec 16, 2014 at 11:49 AM, Roman Cheplyaka <[hidden email]> wrote:
>> On 16/12/14 12:36, Johan Tibell wrote:
>>> On Tue, Dec 16, 2014 at 2:42 AM, Zach Moazeni <[hidden email]
>>> <mailto:[hidden email]>> wrote:
>>>     Another question, by far most packages I have encountered either
>>>     lead with a 0 or a 1 for "A". Does that have some bearing on the
>>>     long term stability that package users should expect in the future?
>>>
>>>
>>> This is something that happens a lot in open source, in Haskell or
>>> elsewhere. We We programmers are afraid of calling something 1.0,
>>> because that somehow means "done", which we never (think we) are. :)
>>> Lots of really stable Haskell libraries (e.g. containers) are still on
>>> version 0.X.
>>
>> Upper bounds contribute to this problem, too.
>>
>> Suppose you've decided that 'containers' is stable enough to be at 1.0.
>>
>> Now all packages need to be updated, because they most probably depend
>> on 'containers < 1' or tighter.
>>
>> We saw something similar with text, people got angry.
>>
>> If a library becomes popular before it reaches 1.0, it probably never will.
>
> I don't understand this. How is bumping 'A' different from bumping
> 'B'? You could just bump 'A' (to 1, for example) instead of 'B' when
> you make an API breaking change, and it's no extra effort for people
> who depend on you.

So I need to wait till I have an API-breaking change in order to mark a
package as stable? That's... ironic.

Also, if the library is stable enough, people would constraint the A
version (e.g. 'containers < 1'), asserting that their package will
probably continue to build even under minor API-breaking changes which
are typical for stable packages. Now, by bumping my A version for a
minor breaking change, I'm acting exactly against their intention,
saying "hey, this is a massive change, you'd better pay attention before
using it". That's not what an actual stable package is supposed to do.

Roman
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Erik Hesselink
On Tue, Dec 16, 2014 at 12:23 PM, Roman Cheplyaka <[hidden email]> wrote:

> On 16/12/14 13:00, Erik Hesselink wrote:
>> On Tue, Dec 16, 2014 at 11:49 AM, Roman Cheplyaka <[hidden email]> wrote:
>>> On 16/12/14 12:36, Johan Tibell wrote:
>>>> On Tue, Dec 16, 2014 at 2:42 AM, Zach Moazeni <[hidden email]
>>>> <mailto:[hidden email]>> wrote:
>>>>     Another question, by far most packages I have encountered either
>>>>     lead with a 0 or a 1 for "A". Does that have some bearing on the
>>>>     long term stability that package users should expect in the future?
>>>>
>>>>
>>>> This is something that happens a lot in open source, in Haskell or
>>>> elsewhere. We We programmers are afraid of calling something 1.0,
>>>> because that somehow means "done", which we never (think we) are. :)
>>>> Lots of really stable Haskell libraries (e.g. containers) are still on
>>>> version 0.X.
>>>
>>> Upper bounds contribute to this problem, too.
>>>
>>> Suppose you've decided that 'containers' is stable enough to be at 1.0.
>>>
>>> Now all packages need to be updated, because they most probably depend
>>> on 'containers < 1' or tighter.
>>>
>>> We saw something similar with text, people got angry.
>>>
>>> If a library becomes popular before it reaches 1.0, it probably never will.
>>
>> I don't understand this. How is bumping 'A' different from bumping
>> 'B'? You could just bump 'A' (to 1, for example) instead of 'B' when
>> you make an API breaking change, and it's no extra effort for people
>> who depend on you.
>
> So I need to wait till I have an API-breaking change in order to mark a
> package as stable? That's... ironic.
>
> Also, if the library is stable enough, people would constraint the A
> version (e.g. 'containers < 1'), asserting that their package will
> probably continue to build even under minor API-breaking changes which
> are typical for stable packages. Now, by bumping my A version for a
> minor breaking change, I'm acting exactly against their intention,
> saying "hey, this is a massive change, you'd better pay attention before
> using it". That's not what an actual stable package is supposed to do.

Is depending on an 'A' component a thing that people actually do for
libraries (other than base, perhaps)? The PVP gives no guarantees
about it, and I haven't seen any specific packages make guarantees
about it either. Without guarantees, it would probably be better for
these people to remove the bounds altogether. I do the same when e.g.
I only depend on the 'Text' type, and no functions from the package.

Erik
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Vincent Hanquez
In reply to this post by Roman Cheplyaka-2

On 16/12/2014 11:23, Roman Cheplyaka wrote:
> So I need to wait till I have an API-breaking change in order to mark a
> package as stable? That's... ironic.
This is one of my issue with the PvP. with the PvP versioning you're not
able to convey any other informations apart from the API "changing".

Which means you can't properly convey:

* major new features: by bumping the major, despite the API not changing
* security (by bumping the minor or patchlevel, regardless if the API
change)
* the stability (bumping to 1.x).

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.

> Also, if the library is stable enough, people would constraint the A
> version (e.g. 'containers < 1'), asserting that their package will
> probably continue to build even under minor API-breaking changes which
> are typical for stable packages. Now, by bumping my A version for a
> minor breaking change, I'm acting exactly against their intention,
> saying "hey, this is a massive change, you'd better pay attention before
> using it". That's not what an actual stable package is supposed to do.
>
Indeed.

--
Vincent
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Corentin Dupont
My opinion is that the version number shouldn't convey the idea of stability. It should be another field :)
In fact in Cabal there is a stability field:
https://www.haskell.org/cabal/users-guide/developing-packages.html#package-properties
But it's not very well specified/used.

Anyway the fact that we like to have "V1.0" to mean "work done" is more a question of aesthetic.
The version number carries three different informations IMO:
- tagging a specific state of the sources,
- give an order between the versions,
- give information about the level of changes.
The third one could be separated. It could be made into a field containing the level of changes, such as "minor changes"/"API breaking changes". Then the version tag could be made what you want, even tagging "V1.0" a minor change.
Just my 2 cent :)



On Tue, Dec 16, 2014 at 12:39 PM, Vincent Hanquez <[hidden email]> wrote:

On 16/12/2014 11:23, Roman Cheplyaka wrote:
So I need to wait till I have an API-breaking change in order to mark a
package as stable? That's... ironic.
This is one of my issue with the PvP. with the PvP versioning you're not able to convey any other informations apart from the API "changing".

Which means you can't properly convey:

* major new features: by bumping the major, despite the API not changing
* security (by bumping the minor or patchlevel, regardless if the API change)
* the stability (bumping to 1.x).

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.

Also, if the library is stable enough, people would constraint the A
version (e.g. 'containers < 1'), asserting that their package will
probably continue to build even under minor API-breaking changes which
are typical for stable packages. Now, by bumping my A version for a
minor breaking change, I'm acting exactly against their intention,
saying "hey, this is a massive change, you'd better pay attention before
using it". That's not what an actual stable package is supposed to do.

Indeed.

--
Vincent

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Felipe Lessa
In reply to this post by Tobias Dammers
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
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Zach Moazeni-2
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 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 <[hidden email]> 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
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe



--
-Zach

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: 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 <[hidden email]> 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 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 <[hidden email]> 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
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe



--
-Zach

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe


_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Why does Haskell PVP have two values for the major version? "A.B..." and a couple other questions

Heinrich Apfelmus
In reply to this post by Johan Tibell-2
Johan Tibell wrote:
> Zach Moazeni wrote:
>> Another question, by far most packages I have encountered either lead with
>> a 0 or a 1 for "A". Does that have some bearing on the long term stability
>> that package users should expect in the future?
>
> This is something that happens a lot in open source, in Haskell or
> elsewhere. We programmers are afraid of calling something 1.0, because
> that somehow means "done", which we never (think we) are. :) Lots of really
> stable Haskell libraries (e.g. containers) are still on version 0.X.

I think the original motivation for major versions of the form A.B was,
at least for me, that preliminary versions can be indicated by A=0.

Personally, I don't consider 1.0 to be "done". Rather version "1.0"
means that the core functionality has been implemented and that the
package authors now have an idea what the core API should look like --
up to future changes. Thus, I think  containers  perfectly well deserves
version 1.0.


Best regards,
Heinrich Apfelmus

--
http://apfelmus.nfshost.com

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe