Pipenv: Versioning

[XenGi]

Is your feature request related to a problem? Please describe.
I'm pretty much disappointed. This project used to be a very good one but when a package manager doesn't understand how important semver is I don't know if I can trust this package manager knowing anything else about packaging anymore.

Describe the solution you'd like
Please go back to semantic versioning or at least explain why the hell you think date based versions are a good idea.

[uranusjr]

I didn’t make decisions on this, and honestly does not have opinions either way. But we are not as knowledge as you are about how great and wonderful SemVer is, and instead of simply saying “you should use semver otherwise you’re bad”, you’d need to actually propose reasons why this is the case, so we can understand how great and wonderful SemVer is. Thank you for your understanding.

[techalchemy]

1) please read the code of conduct, your attitude is highly unpleasant
2) CalVer is a completely acceptable versioning standard and we were only loosely following semantic versioning anyway
3) feel free to stop using pipenv if you don’t understand calver. If you want to learn more about it instead of makin demands, see https://calver.org

Please come back when you can be more constructive

[dvzrv]

While not in tone, in content I'm with @XenGi here.

Changing to a calendar based release style breaks downstream packaging, when trying to get back to a semantic version based release style again. In case that happens, downstream has to do strange things, such as using an epoch (see Arch Linux' epoch for an example).

Such a change should not go unannounced (but maybe I just missed it?). Please be aware of the above issue, when changing versioning style!

One request remains valid though: Where/ when was this decision made?

Apart from that, IMHO calendar based versioning is not great for doing milestones and introducing major changes (as in major version change), as it's bound to time. Therefore I don't think it's a great solution, but now that it was picked, better stick to it...

[dvzrv]

To further the point about the milestone issue: At which version will this milestone aim now?

[techalchemy]

The milestone is somewhat arbitrary and I haven’t decided how to rework it yet. The key element is this: semantic versioning is not something we used strictly in the past, and it is only a declaration of intent. You only need to look through previous issues to see that we had numerous releases where we broke some functionality by accident or fixed something people depended upon being ‘broken’.

Lots of other projects manage to use CalVer and still release changes without things falling apart. Pip itself is also moving to calver. We made this decision at pycon where we had a bunch of maintainers together. We didn’t make a big announcement (we don’t really have infrastructure for this anyway) but calver is definitely new to me personally as a maintainer and adjustment may have a hiccup or two. I’m grateful for any input or advice on the topic, so thanks for the heads up on the challenges arch faces.

At the end of the day we cut pipenv releases when we had them tested enough to release, or when there is a serious bug. Milestones have always been general concepts more than rules. This is just an official way of acknowledging that we never really used semver to begin with.

[XenGi]

This is just an official way of acknowledging that we never really used semver to begin with.

Sorry for my comment earlier. But this is basically the only sentence I wanted to hear before that change. I would have thought, ok not the way I would prefer it but what ever. But for me this change looked like a dev deciding something important with gut instinct and without thinking about pros and cons. And when I'm angry I tend to write unhelpful comments. I'm working on it.

Maybe some more helpful advice:
In my opinion calver makes total sense when you have no public API. Like Ubuntus release names. It's totally fine to name them 17.10 etc. There "API" basically changes with every release anyway. For a program or library others depend on it's better to use semver or something similar so one can better depend on an API state. An alternative would be something like Androids API levels.
Personally I would always prefer semver or just adding up an integer over calver because I find it ugly. But that's just personal preference.

So if you don't want to use semver and don't really care what you use, maybe just count integers like xterm or systemd. It's easier for maintainers then calver and if you decide to go back to another system it's also easier to change.

[Foxboron]

We didn’t make a big announcement (we don’t really have infrastructure for this anyway) but calver is definitely new to me personally as a maintainer and adjustment may have a hiccup or two.

You do have infrastructure for announcements regarding releases on github. Example: https://github.com/golang/dep/releases. I updated pipenv for Arch Linux two days ago and that was the first page i looked at for a rationale for suddenly changing versioning scheme.

[bryant1410]

With this change, how can I tell if a version intends to break changes?

[XenGi]

@bryant1410 You can't. You basically have to read the changelog before you update. afaik semver is the only way to show a user when an API will change without the need to read any documents. But the project decided to not do semver so there is simply no way to see if the API changed without reading the release notes.

[bryant1410]

@XenGi okay. Btw, I think we should always read the changelogs before updating anything :sweat_smile:

I started discussing this with CalVer guys in mahmoud/calver#4 In my opinion, it's a good idea, but we all can benefit if it includes API-break in the versioning scheme.

Apart from it, I agree with @uranusjr and also with @kennethreitz that lately some people are being somewhat aggressive when they disagree on something widely used. We can't just go around disrespecting other people just because we disagree.

Anyway, I agree with @dvzrv that such a change should not go unannounced (and it should do ahead of time). Maybe you guys could also write in the docs about it, and when should we expect some part of the API to be broken.

[techalchemy]

Ideally we won't break the API, it's somewhat rare that we do this intentionally. My main point is that most times when we have broken apis, it has been because;

• We intended to, so we did a major version bump and still experienced backlash (we still have people on version 9 who expect / demand support)
• We did so accidentally (it was a bug) and experienced a flood of issues demanding to know why we don't announce and properly respect semantic versioning when breaking APIs
• We didn't have test coverage for a specific use case and a change to some core logic broke usage we didn't know about
• We fixed usage that was already broken, but people relied upon the broken behavior

The ubuntu example is kind of apt, because we aren't just exposing an API here -- the resolver logic we have is incredibly complex and it's basically impossible to determine whether a change to resolver logic should be a major, minor, or patch release. Even when all tests pass, system-to-system behavior varies wildly. As a consequence semantic versioning can _only_ tell you about our API usage in many cases. We recently had a resolver flag that allowed eggs to be prioritized over wheels and sdists. We fixed that in a patch release, but I'm sure it broke functionality for someone...

[eli-schwartz]

I'd argue date-based versioning is actually pretty counter-intuitive except in cases like Ubuntu, where the actual thing they are releasing is, in fact, a date... the extremely regularly scheduled date at which the current code, whatever that may be, was snapshotted for release. Dates make sense, because there's a guarantee built into the release cycle that such a version will be superseded in X time, and stop being supported in XX time.

CalVer therefore imparts uniquely meaningful information in that case.

It doesn't, when the date referenced is merely the release date with no guarantees as to what that release date means. Does pipenv 2018.05.18 tell me that on the date 2018.08.18 I should look for a new version because I'm clearly running months out of date? No it doesn't:

At the end of the day we cut pipenv releases when we had them tested enough to release, or when there is a serious bug.

systemd decided they don't want to use semver, so they consider everything a major release and just increment an integer by one. This lets me see how much has changed between two given versions, without making any promises about the API. It's even fully compatible with semver.

It's the kind of thing that gives you the flexibility if you really need to, to fork off a maintenance branch and release a hotfixed .1 release containing this one really important bugfix that you really want users to have, even though you do not want them to have all the many non-hotfix changes on master. Interestingly, that's basically what Firefox (which the CalVer advocacy article brings up) now uses.

What would 2018.05.18.1 mean, especially if it's actually released on the 23rd and not in the first 10th of the day of May 18? Should you release 2018.05.23 even though it looks exactly like any other version, but doesn't correspond to the git master from that date? What does that version tell me?

Changing to a calendar based release style breaks downstream packaging, when trying to get back to a semantic version based release style again. In case that happens, downstream has to do strange things, such as using an epoch (see Arch Linux' epoch for an example).

I think PEP 440's epoch is just as ugly though. :p It's hardly unique to downstream.

[kennethreitz42]

We're not seeking active feedback on this part of our product offering — but thank you for your feedback. This was a team decision, and we made it together for many reasons.

Semantic versioning, while ideal, was not actually what was in place, due to a historical typo. If we were using semantic versioning, we'd be at v0.7.x right now.

[bryant1410]

Okay, good to know. Is there any public place where that discussion and future ones can be viewed?

[kennethreitz42]

this happened IRL, unfortunately ;)