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