search

yiisoft / yii2

Yii 2: The Fast, Secure and Professional PHP Framework
http://www.yiiframework.com
BSD 3-Clause "New" or "Revised" License
14.24k stars 6.91k forks source link

Switch to plain semver (three version digits) #15983

Closed schmunk42 closed 6 years ago

schmunk42 commented 6 years ago

What steps will reproduce the problem?

Currently Yii is using a four-digit versioning, which is not 100% Semantic Versioning and it does not play very well with composer.

Two of the most commonly used operators ^ and ~ don't work well with the current versioning.

What is the expected result?

Have a concise way to define constraints for the core framework.

What do you get instead?

There's no operator which can be used in a sane way with the current versioning.

Additional info

Q A
Yii version any

You can read the prologue to this issue starting from https://github.com/yiisoft/yii2-phpunit/pull/2#issuecomment-375270353

I know this is a huge change and I'd avoid it if there'd be a reasonable alternative, but neither changing semver, nor introducing a new operator to composer seems to be one.

Possible naming:

Tasks

samdark commented 6 years ago

I was against the renaming for quite some time but since Composer doesn't work with current versioning schema well, it makes sense.

We can call the framework just Yii and start with version 3.0.0.

samdark commented 6 years ago

Need more opinions on the matter.

schmunk42 commented 6 years ago

We can call the framework just Yii and start with version 3.0.0.

How would you name the yiisoft-repo(s) in such a case?

We have like all extensions named yii2-... in the ecosystem, which I like very much, you instantly see if the extension is what you are looking for. A change from version 2.0.15.2 to 3.0.0 does not neccessarily mean an extension is not working anymore.

A problem is, that yii-... is already taken by Yii 1.0 and 1.1. For me Yii3 would be something completely new, like the switch from Yii1 to Yii2, which also relied on many new features of PHP. But Yii3 could be released in version 1.0.0 in some day in the future.

bizley commented 6 years ago

Have you considered taking back yii repo name with version 3? I know it would be quite a surprise for everyone with composer set to "yiisoft/yii": "*" but let's be honest - it should not be set like that in the first place.

schmunk42 commented 6 years ago

Have you considered taking back yii repo name with version 3? I know it would be quite a surprise for everyone with composer set to "yiisoft/yii": "*" but let's be honest - it should not be set like that in the first place.

I think this would be very confusing and the change of breaking things is also rather high. A lot of people are still using Yii1 out there.

Another option, although I don't like it very much, is to use:

Like it is already done with yiisoft/di, but should all other repos be renamed too? And we'd loose all the GitHub stars...

My vote goes to keeping yii2 as the name and let it's version be a separate thing.

samdark commented 6 years ago

A change from version 2.0.15.2 to 3.0.0 does not neccessarily mean an extension is not working anymore.

It's likely so.

samdark commented 6 years ago

Keeping Yii2 is OK as well.

Aradiv commented 6 years ago

i would also prefer Yii2 to use semver. what is currently done as Yii 2.1 should be yii2 3.0.0

if there will be an almost complete rewrite (like yii to yii2) this could get also new sets of repositories as yii3 (or whatever you want to call it)

cebe commented 6 years ago

~2.0.15.2 - gives you only updates below 2.0.16, which is clearly too restrictive

given that Yii releases may contain upgrade notes and changes to the application may be needed on upgrade, having the Yii version fixed to a patch release is not uncommon and I'd even recommend using such a constraint.

cebe commented 6 years ago

In the rare case where you need to require a minimum patch version but want to allow upgrades on the normal releases, you can specify a contraint like ~2.0.14,>=2.0.14.1

https://semver.mwl.be/#?package=yiisoft%2Fyii2&version=~2.0.14,%3E%3D2.0.14.1&minimum-stability=stable

samdark commented 6 years ago

Yes but that's quite counter-intuitive.

cebe commented 6 years ago

Yes but that's quite counter-intuitive.

imo its okay to use a counter-intuitive constraint in a rare case and proceed with the existing versioning strategy without creating confusions like Yii2 version 3.

rugabarbo commented 6 years ago

Thoughts about Yii2 version 3 make me cry.

schmunk42 commented 6 years ago

Moreover, many extensions have ^2.0.x or ^2.0.x.y as their constraint for the core framework. If the next major version is released as 2.1.0 those will get installed and many of them won't work or even worse - they'll have weird issues.

Raising the major version of a constraint should be deliberate decision.

Why is Yii2 version 3.0.0 so confusing? The former is the name the latter "just" a (semantic) version.

rugabarbo commented 6 years ago

Why is Yii2 version 3.0.0 so confusing?

cos 2 != 3

cebe commented 6 years ago

Moreover, many extensions have ^2.0.x or ^2.0.x.y as their constraint for the core framework.

this is wrong and we should educate users more about the impact. Wrong usage is not a reason to change the strategy.

cebe commented 6 years ago

We currently have this note in the release news:

https://www.yiiframework.com/news/165/yii-2-0-14-is-released Since there is Yii 2.1 in development now, make sure you have a version constraint in your composer.json, that does not allow it to be installed automatically on update, so when next major version of Yii is released, your project won't break by itself. A version constraint that does not include 2.1 is for example ~2.0.14, make sure you do not have >= or * in version constraints in composer.json.

We could add something about ^ to that.

bizley commented 6 years ago

BTW, this

And we'd loose all the GitHub stars...

is not a problem, all stars are kept.

schmunk42 commented 6 years ago

The number is there - it is like it is.

this is wrong and we should educate users more about the impact. Wrong usage is not a reason to change the strategy.

This is not wrong at all, it's clearly documented how to use those operators with composer:

The ^ operator behaves very similarly but it sticks closer to semantic versioning, and will always allow non-breaking updates. This is the recommended operator for maximum interoperability when writing library code.

https://getcomposer.org/doc/articles/versions.md#next-significant-release-operators

I am sorry to say, but Yii2 is just doing this wrong.

schmunk42 commented 6 years ago

Another related problem with composer require https://github.com/composer/composer/issues/6816

rugabarbo commented 6 years ago

I think version 3.0.0 should be either in the repository yii3, or in the repository yii. The first one is a bad solution, because for each next version you will need a new repository (yii4, yii5, etc.) and brand name (Yii 4, Yii 5 and so on)

So, good solutions are:

  1. Doesn't use semver at all
  2. Use Yii / yii naming for all things (without digits)
bizley commented 6 years ago

I really like yii/yii. Other frameworks like Symfony, Laravel, Drupal, are using this pattern.
I don't see any benefits of not using semver so I don't think solution 1 should be considered at all.

schmunk42 commented 6 years ago

Not using semver is IMHO not a good solution, given that composer is an integral part of our tooling.

Renaming a repo can be done, but hell breaks loose, if the old name is accidentially recreated, because all traffic will go to an empty repo - AFAIK this happend before with bower packages.

bizley commented 6 years ago

This is great moment for renaming - with the release of 2.1.

Team efforts will focus on the new version anyway so we can do the numbers by the book.
And as for the 2.0.* - why not switch to semver if current 2.1 gets new name? Let 2.0.16 become new 2.1.0 and Björn Stronginthearm is your uncle...

rugabarbo commented 6 years ago

@frontbear

If use this approach, each version requires a lot of work to move to a new name for the repository and brand (create new repo, rewrite docs, etc.)

frontbear commented 6 years ago

How about doing some renamed:

yiisoft/yii2 -> yiisoft/framework yiisoft/yii2-framework -> yiisoft/framework-src

yiisoft/yii2-redis -> yiisoft/yii-redis yiisoft/yii2-phpunit -> yiisoft/yii-phpunit yiisoft/yii2-queue -> yiisoft/yii-queue ...

Forin commented 6 years ago

What is the main problem?

If it is the four-digit versioning, why don´t you simply get back to plain semver (three version digits)?

schmunk42 commented 6 years ago

just thinking loud...

yii2:2.0.15
yii2:3.0.0
   ^ ^ ^ ^
   | | | patch
   | | minor
   | major
   "general" (won't ever change for Yii2 Framework)

Pros

Cons

cebe commented 6 years ago

operator behaves very similarly but it sticks closer to semantic versioning

...

I am sorry to say, but Yii2 is just doing this wrong.

Yii2 is not using semver so this operator does not fit for Yii. Using it for Yii is wrong usage.

Why is Yii not simply using semver?

The short answer: because it is not simple to use semver. I would even say it is impossible for software that is as complex as Yii to follow semver and claiming to use semver would be a lie.

The problem of backwards compatibility (BC) and the distinction between bug and feature are not trivial. To get an idea about the complexity of BC, see https://github.com/yiisoft/yii2/blob/2.0.15/docs/internals/bc.md For bug vs. Feature XKCD has a good illustration: "every change breaks someones workflow". every change breaks someones workflow.

Yii is a complex software designed to be extensible in a lot of ways. When we want to make progress in developing Yii, we can not keep 100% BC. Claiming to use Semver, would be a lie as we can not gurantee perfect compatibiliy for every use case. We need to accept that upgrading Yii might break some applications. We try to keep the impact of these breaks as low as possible and write UPGRADE.md documentation to explain changes that we know of. But its not always possible to see breeaking changes beforehand.

Semver is an ideal world, it makes assumptions about software development that do not apply to complex software like Yii. Semver fits well for small libraries or tools, where the use cases are straightforward or directly visible, it does not fit for Yii, so imo we should not try to use semver as it is impossible to do so.

schmunk42 commented 6 years ago

If I would be an external user and read this without knowing about Yii, I'd think: "Look at this, they have no idea what's going on in their software and they are not even trying to stay backward compatible." Of course I am exaggerating here.

For sure there's no guarantee, but nobody will or can sue you if there's a BC-break.

The more complex the software, the more important it is to have semantic versioning. There are several things which would indicate a minor or major upgrade (https://semver.org/#summary). The entire public API of Yii is fully documented (https://semver.org/#documenting-the-entire-public-api-is-too-much-work)

Now the situation is: Yii is releasing a new patch version (it's actually a minor version - I know) from time to time and it looks like it should be no problem to update, because literally all other software we use works like that - please leave aside that there can be errors made by developers, we're all humans.

All kinds of changes are released in 2.0.x - most of the time this is fine, but on several occasions it would have been so much easier, if there'd have been a clearer difference between minor and patch version; latest example for me was Exceptions, when echo'ing content in controllers instead of returning it. Yes, this is not clearly covered by API changes mentioned in semver, but things like that can be anticipated.

Semver is not only import for library versioning, it's way more important for library constraints to the framework! A very simple library can have a looser constraint like ^, while a pretty complex module might be better off with ~.

The leading number 2 in the version string is pointless, useless - it will never ever change in the current versioning scheme, actually it can be removed.

sergeymakinen commented 6 years ago

Em. Semver is not something a software has to follow. It's just a versioning scheme with its own rules. You follow it and increment major numbers (because Yii do break BC and surely will) or you don't. My personal opinion is that semver "Yii2 ver x.x.x" where x.x.x follows semver simply reduces wtfs per minute while upgrading packages. Especially for people not going to dig around issues to find out the Yii's versioning scheme. @schmunk42 got a long explanation for this. 👍

rob006 commented 6 years ago

@sergeymakinen It may increase wtfs per minute overall - you will get it every time when you will see something like Yii 2 3.0 :D

Also, I'm absolutely sure that people will create some crazy variations like Yii3 or Yii 2.3.0, so nobody will know what Yii2 really means.

schmunk42 commented 6 years ago

Yii2 is the name of the software, like TYPO3 :hear_no_evil:, Db2 or OS X.

Why should anyone call it Yii2 Yii3? It will be Yii2 forever, we agree here :+1:

The :two: is part of its name, of the repo name, of all extensions whether core or contrib, tags on stackoverflow - Yii2 will never be called Yii3, I promise. :hand:

rob006 commented 6 years ago

Yii2 is the name of the software, like TYPO3 :hear_no_evil:, Db2 or OS X.

Actually, only OS X is similar to Yii 2, since it has pre-X releases and did not start as OS X (there was a Mac OS 8 and Mac OS 9, same as there was a Yii 1). And guess what - it has fixed 10 in version. :D

Yii2 will never be called Yii3, I promise.

I don't believe it. I've done several job interviews and people has a problem to specify which version of Symfony, they were using. I can't even imagine how confusing for them will be Yii 2 3.0.

And framework name is Yii - you should go to official website or read some docs to realize this.

schmunk42 commented 6 years ago

I don't believe it. I've done several job interviews and people has a problem to specify which version of Symfony, they were using.

:rofl: LOL, they don't even have a number in their name. Do you use Yii 2.0, because your employees then know which version of the framework they are using?

Maybe, because they are using semver, it is not their "golden calf". Thou shall have no other major version numbers beside me.

And framework name is Yii

But you told me 4 days ago it has to be referenced as "Yii 2" - https://github.com/yiisoft/yii2-phpunit/pull/2#issuecomment-375719220

you should go to official website or read some docs to realize this.

Second link's headline is The Definitive Guide to Yii 2.0 - btw Prado docs are missing, they have as much in common with Yii 1.0 as Yii 1.1 with Yii 2.0. [/sarcasm]

samdark commented 6 years ago

@rob006 Windows 10 as well. It's now similar to OSX in its versioning.

schmunk42 commented 6 years ago

btw: Windows 10 is currently in Version 1709 / Build 16299; OS X is actually called macOS nowadays

rob006 commented 6 years ago

Windows 10 is currently in Version 1709 / Build 16299

Which is 10.0.16299.334 - https://en.wikipedia.org/wiki/Windows_10 1709 is not really a version, it is more like a codename (it comes from September 2017).

schmunk42 commented 6 years ago

Some stats about the extension ecosystem, analyzed via a testing project, which includes as much extensions as possible.

Judge for yourself how carefully the special versioning part of Yii2 is read.

Yii2 Extension Ecosystem.pdf

Note: Not all of them are in their latest version, due to constraints; which raises another problem, that if you upgrade the core to 2.1, several extensions might downgrade to an older version, since their constraint matched 2.1 there! We also had that issue several times before.

Yes, we can not fix this for totally broken constraints like * or >=2.0.4, but even if you had "the wrong" constraint ^2.0.4 and "fixed" it to ~2.0.4 - your extension might still break, the chances are definitely higher than with 3.0.0.

My huge concern is that a 2.1 release would break large parts of the ecosystem or at least the user-experience when installing extensions. We should do everything to avoid and minimize that.

Example:

  • install a fresh "2.1" app template
  • install first extension -> Exception
  • install second extension -> Exception
  • curse the framework and never touch it again

Some rather popular examples with broken constraints for 2.1:

fcaldarelli commented 6 years ago

I think that the product is Yii and not Yii2, the last number should only help us to understand what version we are referring to. Exactly how Apple moved from OS X to macOS, the repositories could be renamed in yii/yii, with applied right version.

But at the same time we could name publically Yii with his last version that made breaking changes from previous.

So the next 2.1 version, I'd call it Yii 3, so when users will start to post questions on github, forum and stack overflow, it will be simpler to specify and understand what version we are talking about.

At last, I'd proceed in this way:

For extensions developers, I'd suggest to use prefix with major version, for example yii3-ckeditor.

schmunk42 commented 6 years ago

While yii/yii would be cool, I fear this name is already taken, see https://github.com/yii

bizley commented 6 years ago

Name Squatting Policy

fcaldarelli commented 6 years ago

Reusing https://github.com/yiisoft/yii ?

schmunk42 commented 6 years ago

Reusing https://github.com/yiisoft/yii ?

Nope, I don't think this is really an option. To many things can break, it also won't help when there'll be Yii3 some day in the future. Which would be a complete rewrite like Yii -> Yii2.

I would definitely stick with the current repos and naming yii2-....

Organization name: yiisoft Product name: yii2 Version: x.y.z

Just another thing about yii2 vs. Yii 2.0 - the former is much more suitable for searching and tagging things on the internet.

fcaldarelli commented 6 years ago

Publically Yii v. 3.x.y could be called Yii3, so users can distinguish the versions.

Inside the package, I'd use always yii v.3.x.y, otherwise we could have yii3 package with version 1.x.y., that could be confusing.

schmunk42 commented 6 years ago

Publically Yii v. 3.x.y could be called Yii3, so users can distinguish the versions.

But it is not Yii v3 it would be: Yii2 Framework 3.0.0. Nobody says IBM Db11, Microsoft Windows 1709 or TYPO5 CMS.

fcaldarelli commented 6 years ago

Infact you will call it Yii3, but inside it is Yii version 3.x.y

schmunk42 commented 6 years ago

I think we should agree here and now, that there will never ever be a project called Yii3, otherwise we'll have the discussion again :roll_eyes: [/sarcasm]

Yii without any addition was mostly used for either Yii 1.0/1.1 or as a general term, like a concept, so Yii version 3.x.y would belong to this repo: https://github.com/yiisoft/yii - but I hardly doubt it will be ever created.

Question: When you really call out the name of our beloved framework, what do you say? In my case it's Yii-Zwei (German).

Yii-Dos, Yii-Dva, Yii-Two, Yii-Due, Yii-Dyo, Yii-Deux, Yii-Er. Let's Pick one, all problems solved :sweat_smile:

githubjeka commented 6 years ago

Simple:

hiqsol commented 6 years ago

+1 to @githubjeka But taking into account new yii is going to be split into components it should be: yiisoft/core, yiisoft/console and so on like already existing yiisoft/di