yii2 🚀 - Switch to plain semver (three version digits)

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 on 25 Mar 2018

👍5

Need more opinions on the matter.

samdark on 25 Mar 2018

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.

schmunk42 on 26 Mar 2018

👍1

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.

bizley on 26 Mar 2018

👍3

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:

yiisoft/core
yiisoft/framework

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.

schmunk42 on 26 Mar 2018

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 on 26 Mar 2018

Keeping Yii2 is OK as well.

samdark on 26 Mar 2018

😕5 👍3

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)

Aradiv on 26 Mar 2018

👍6 ❤1 🎉1

~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 on 26 Mar 2018

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

cebe on 26 Mar 2018

Yes but that's quite counter-intuitive.

samdark on 26 Mar 2018

👍3

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.

cebe on 26 Mar 2018

👍1

Thoughts about Yii2 version 3 make me cry.

rugabarbo on 26 Mar 2018

😄2

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.

schmunk42 on 26 Mar 2018

Why is Yii2 version 3.0.0 so confusing?

cos 2 != 3

rugabarbo on 26 Mar 2018

👍4

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 on 26 Mar 2018

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.

cebe on 26 Mar 2018

BTW, this

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

is not a problem, all stars are kept.

bizley on 26 Mar 2018

The number is there - it is like it is.

either view it as a "super" version number (something above major, which won't be changed for this repo anyway)
or create a new repo like mentioned in the initial posting
or push all of yii2's history onto yiisoft/yii :speak_no_evil: so we can user semver

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 on 26 Mar 2018

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

schmunk42 on 26 Mar 2018

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:

Doesn't use semver at all
Use Yii / yii naming for all things (without digits)

rugabarbo on 26 Mar 2018

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.

bizley on 26 Mar 2018

👍7 ❤3

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.

schmunk42 on 26 Mar 2018

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...

bizley on 26 Mar 2018

👍1

@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.)

rugabarbo on 27 Mar 2018

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
...

frontbear on 27 Mar 2018

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)?

Forin on 27 Mar 2018

just thinking loud...

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

Pros

four digits, like now
semver compatible
same way as you'd write it with composer require
no rebranding required for every major release "Yii 2.0 Framework", "Yii 2.1 Framework", "Yii 2.3 Framework", just Yii 2 Framework
if referencing it you could still write "Yii 2:3 Framework"
"unusual" :see_no_evil: Yii versioning clearly marked with a colon :wink:

Cons

version jumps from 2.0 to 2:3
no version 2.1
version 2.0 and 2:2 are actually equivalent

schmunk42 on 27 Mar 2018

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". .

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.

cebe on 27 Mar 2018

😕2 👍2

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.

schmunk42 on 27 Mar 2018

👍6

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. 👍

sergeymakinen on 27 Mar 2018

👍4

@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.

rob006 on 27 Mar 2018

😄2

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:

schmunk42 on 27 Mar 2018

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.

rob006 on 27 Mar 2018

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]

schmunk42 on 27 Mar 2018

👎2

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

samdark on 27 Mar 2018

👍1

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

schmunk42 on 27 Mar 2018

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).

rob006 on 27 Mar 2018

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

134 extensions depending on yii2
- 68 with a broken constraint for 2.1 or 3.0 (ie. unbound)
- 22 with a broken constraint for 2.1
- 44 with an OK constraint for 2.1 (only 19 of them with a "well-maintained" constraint)

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:

schmunk42 on 28 Mar 2018

👍4

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:

rename the repository in yii/yii
when we need to make a bigger breaking changes version, to upgrade the major; so next version should be Yii 3 and not Yii 2.

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

FabrizioCaldarelli on 29 Mar 2018

👍7

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

schmunk42 on 29 Mar 2018

Name Squatting Policy

bizley on 29 Mar 2018

👍2

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

FabrizioCaldarelli on 29 Mar 2018

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.

schmunk42 on 29 Mar 2018

👍2 😕1

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.

FabrizioCaldarelli on 29 Mar 2018

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.

schmunk42 on 29 Mar 2018

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

FabrizioCaldarelli on 29 Mar 2018

👍3

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:

schmunk42 on 29 Mar 2018

Simple:

Create yiisoft/yii-framework repository
Start from version 3.0.0

githubjeka on 29 Mar 2018

👍4

+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

hiqsol on 30 Mar 2018

❤1 🎉1 👍1

@hiqsol @githubjeka How would we name extensions then (currently yii2-...)?

schmunk42 on 30 Mar 2018

How would we name extensions then (currently yii2-...)?

I think that extensions should contain major version component, such as:
yii3- , yii4-, yii5-

FabrizioCaldarelli on 30 Mar 2018

👎3

I think extensions should be named yii-extension-name or as you want. And you can see require Yii version in composer.json

githubjeka on 30 Mar 2018

👍3

Releasing framework as a new package (yiisoft/yii-framework) will mess up dependencies of all existing projects and extensions, since they require yiisoft/yii2 and you can't have installed both yiisoft/yii2 and yiisoft/yii-framework since they share the same namespaces. This will make impossible to have extensions compatible with both Yii 2.0 and Yii 2.1 (AKA Yii 2 3.0 AKA Yii 3.0), and will definitely slow down migration to 2.1.

rob006 on 30 Mar 2018

It would be easier to have yii2semver org with yii2semver/yii2-* packages released in semver-way. yiisoft/yii2:2.0.15 will be yii2semver/yii2:2.15.0 and yiisoft/yii2:2.1.0 will be yii2semver/yii2:3.0.0. All semver fans are happy and we're not creating new repo for each major release. :D

rob006 on 30 Mar 2018

You want to use in a project

 "php": ">=7.1",
 "yiisoft/yii2": "2.0.15",
 "yiisoft/core": "~3.0.0",

and rewrite project step-by-step to new features ?
Is this possible with yii1 and yii2 ?

githubjeka on 30 Mar 2018

and rewrite project step-by-step to new features ?

No, I'm talking about extension compatible with both Yii 2.0 and 2.1 because none of BC breaking changes affects it. I could use "yiisoft/yii2": "~2.0.15 || ~2.1.0" to achieve this, but this is impossible if 2.1 will be released as a separate packages.

Is this possible with yii1 and yii2 ?

Yes, it is. AFAIK this was the only reason to release Yii 2.0 as separate package.

rob006 on 30 Mar 2018

Reading this: https://github.com/composer/packagist/issues/47#issuecomment-271962248 - I think renaming is off the table, it creates too much issues.

If done as yiisoft/core:3.0.0 I'd add a conflicts: yiisoft/yii2 since it's more or less the same code, completely different than a transition from Yii1 to Yii2.

schmunk42 on 30 Mar 2018

OK. New simple solution:
Just create new release 3.0.0 instead 2.1 in this repository.

githubjeka on 30 Mar 2018

🎉3 👍3

So we're back to Yii 2 3.0 "solution"...

rob006 on 30 Mar 2018

😄3

I don't see any problem for Yii2 in this case

githubjeka on 30 Mar 2018

👍2

https://github.com/yiisoft/yii2-queue/issues/223

samdark on 31 Mar 2018

https://github.com/yiisoft/yii2-faker/pull/34

samdark on 31 Mar 2018

The name Yii2 was used with the introduction of a new version of Yii. It does not make very much sense to me to reuse this naming when moving to a 3.0 or 4.0.

Once we keep it, the harder and more confusing it will be in the future to drop it. It will then likely always be Yii2.

IMHO, this is the right time to do it right and start with a clean start at yii/yii. It is the most intuitive and consistent way IMHO.

dynasource on 31 Mar 2018

👍10 👎2 ❤1 🎉1

@dynasource This question remains still open ... how should extensions be named then?

It is also not taken into account, that there's a huge difference between Yii 1 and Yii 2, which was a complete rewrite, while 2.1/3.0 is "just" a major version bump, due to a few API changes.

The name Yii2 was used with the introduction of a new version of Yii.

This was not just a new version, as said, it was a complete rewrite.

Once we keep it, the harder and more confusing it will be in the future to drop it. It will then likely always be Yii2.

I strongly hope that Yii2 will stay around for a long time, in fact that's one of the reasons we're using it, because releases and upgrading is very plannable.

IMHO, this is the right time to do it right and start with a clean start at yii/yii. It is the most intuitive and consistent way IMHO.

While others complain that changing the versioning scheme (in a major release) is a no-go, now we're talking about throwing everything away and start over with an old burnt name (yii = Yii 1.0/1.1)?!

schmunk42 on 31 Mar 2018

Haven't really thought this could be an alternative, but how about

21.0.0

from https://github.com/yiisoft/yii2-phpunit/pull/2#issuecomment-375718695

schmunk42 on 31 Mar 2018

This question remains still open ... how should extensions be named then?

This is not a discussion about extensions' names. They can be named whatever. The only thing that matters is the Yii version they required.

bizley on 31 Mar 2018

They can be named whatever.

There's also a policy that they shoud be named yii2-..., which is a very good thing btw.
All extensions from yiisoft and almost all in the ecosystem are following that. Therefore it has to be taken into account; same goes also for things like tags on Stackoverflow.

schmunk42 on 31 Mar 2018

@schmunk42: whether or not it was a complete rewrite. Does it really matter? There will be many rewrites in the future (as history has proven). In the future, nobody will really care.

I think the naming of Yii2 as a repo has been a bit unfortunate regarding Github repos & composer versioning. This topic is a clear example of it.

Regarding extensions. Why should a version be included. What if an extension suits both Yii2 and Yii3?

dynasource on 31 Mar 2018

whether or not it was a complete rewrite. Does it really matter?

I think so, to me that's what's versioning about. It's a huge difference if you have a rewrite or a major version bump.

There will be many rewrites in the future (as history has proven). In the future, nobody will really care.

There have been two rewrites in ~12 years (if I include PRADO 3) - why should you not care about that?
For us it's highly important not have a rewrite every two years, because we had to put a lot of work in rewrting our extensions for Yii2. It was the same when we moved from PRADO to Yii.

It's a key point to me if a framework can offer such a high degree of code-stability. Actually Yii is the most enterprise-grade framework for PHP to me.

I think the naming of Yii2 as a repo has been a bit unfortunate regarding Github repos & composer versioning. This topic is a clear example of it.

I agree :)

Regarding extensions. Why should a version be included. What if an extension suits both Yii2 and Yii3?

But it's not the version it's the name. The current version is 2.0.15.

Why can't we just view that separately?

schmunk42 on 31 Mar 2018

To sum up problems:

Framework versioning policy differs from extension versioning policy. It creates confusion.
Framework versioning policy doesn't work well with usual Composer constraints. Especially the fact that we have both 2.x.x and 2.x.x.x.
We don't have a clear way to specify that extension is for Yii 2.1. There are 2.1.x versions for some extensions already. We have to make fixes for 2.0 and release 2.1 compatible versions. We've created 2.1 branches for some extensions but for some extensions there are 2.1.x versions already so it won't work.

samdark on 31 Mar 2018

Exactly, for this reason I suggested to prefix all extension package with Yii major version and change framework major version whenever there was a breaking change;
I think that Yii 2.1 should be named Yii 3.0, because there are breaking changes.

Finally, from developer point of view, I think that there would be less breaking changes or with softer approach, because now we have to update working part of our projects every 2-3 years. Can we discuss also about this, giving more time to deprecated methods before to be deleted from code and analyze what breaking changes are really needed? I know that this is another question different from current, but I think that also in this case there should be a clear plan.

FabrizioCaldarelli on 31 Mar 2018

Let's discuss that separately.

samdark on 31 Mar 2018

The yiisoft extension versioning is done completely correct at the moment.
It won't be possible to keep all extensions and the core framework on the same version anyway.

I mean, are people here, who think, all yiisoft extensions have to stay on 2.x versions forever? If so, all extensions in the ecosystem should have done the same. This would make no sense at all.

I suggested to prefix all extension package with Yii major version.

Is there any other project which does that?
Or is it just prefixed with the name of the project, I might have said this before, I apologize.

schmunk42 on 31 Mar 2018

@schmunk42 for 2.0 — yes. But how to deal with the 2.1.x extension versions that do exist already and 2.1 branches that indicate Yii 2.1 compatibility?

samdark on 31 Mar 2018

@samdark Moving to semver will not change anything in this matter. Bounding extensions versions to framework versions is impossible, we should not even try that. Required framework version should be specified in composer.json constraints, nothing more.

rob006 on 31 Mar 2018

👍2

Well, yes.

samdark on 31 Mar 2018

But how to deal with the 2.1.x extension versions that do exist already and 2.1 branches that indicate Yii 2.1 compatibility?

2.1 versions that already exist, like https://github.com/yiisoft/yii2-mongodb/releases are there because there were not only patch releases, all good.

If other extensions which are compatible with version 2.0.15 and 3.0.0 of the framework they can be released as 2.1.0.

If they are only compatible with 3.0.0, they should be bumped to 3.0.0 also (if they'd be in 3.0.0, they'd be bumped to 4.0.0)

schmunk42 on 31 Mar 2018

Is there any other project which does that?

I don't know other project which does it, but what other guideline to developers to allow to distinguish extensions compatibilities?

If we want to use always same prefix for extensions, how can we explain extension compatibility with the framework?

FabrizioCaldarelli on 31 Mar 2018

I don't know other project which does it, but what other guideline to developers to allow to distinguish extensions compatibilities?
If we want to use always same prefix for extensions, how can we explain extension compatibility with the framework?

Also as mentioned above, composer does that for you. You can also look into composer.json or view it on packagist.

schmunk42 on 31 Mar 2018

So if I develop an extension for Yii 2.0, with version 3.1.5.
Then I want to upgrade it to Yii 2.1, let's say version 4.0.0.
If I want to continue to support my extension for Yii 2.0, I have to remember that I have to remain under version 4.0.0, otherwise there will be a mess between versions. Is this an organized way to keep and guarantee maintenance for extensions?

FabrizioCaldarelli on 31 Mar 2018

👍2

Yes, the question of @FabrizioCaldarelli is exactly what I've meant.

samdark on 31 Mar 2018

If I want to continue to support my extension for Yii 2.0, I have to remember that I have to remain under version 4.0.0.

Yes, that's how it works. But I fail to see how this is connected to this discussion.

@samdark What issues do you see?

Just as an example: There's even a 2.2.0 for yii2-twig - absolutely fine, should even be a 3.0.0 since the twig constraint was raised in the major version. We actually had some issues with that, a co-dev used methods which were no longer available in Twig 2.x - would have been clearer if the major version of yii2-twig had been raised also.

otherwise there will be a mess between versions.

Sure, you can not really introduce breaking changes for your version 3.

Is this an organized way to keep and guarantee maintenance for extensions?

Can't think of any better.

schmunk42 on 1 Apr 2018

@schmunk42 for example, I want to maintain extension for both 2.0 and 2.1 versions of the framework. For both I want to introduce a breaking change. How would versions look like?

samdark on 1 Apr 2018

@FabrizioCaldarelli, @samdark Major release of your extension should represent BC breaking changes in your extension, not in framework core. You could support both versions of Yii on one major version (3.1.x for Yii 2.0, 3.2.x for Yii 2.1) and let the composer choose right version (from constraints like ~3.1). After BC break, you will get 4.0.x for Yii 2.0 and 4.1.x for Yii 2.1.
Also you could always release it as a separate package - no one will forbid you this. ;) But let's be honest - usually the version for Yii 2.0 will no longer be actively developed and will only get minor changes.

rob006 on 1 Apr 2018

👍1

I want to maintain extension for both 2.0 and 2.1 versions of the framework. For both I want to introduce a breaking change. How would versions look like?

If you have an extension which is compatible with both versions, just increment the major number.
If you have a ie. 2.2.0 and 3.0.0 of the extension you can still increase to upper one to 4.0.0 - but again how is this connected to the versioning discussion of the framework? You are introducing a breaking change in the extension.

At least - and I also said this before - you have bit more room to maneuver for 2.2.0, instead of pretending to do patch versions only. Semver helps you here - it does not limit you or creates confusion.

schmunk42 on 1 Apr 2018

@rob006 when you develop an extension, you don't plan versioning at start, based on all future versions that you want to support. Otherwise we should give guidelines to versioning an extension at start, so it will be compliant with all future version of framework. For example, use 2.1.x.z,so we can support until first two level of version number. But I think that this way is too much strict.

FabrizioCaldarelli on 1 Apr 2018

😕1

OK. Extensions part seems to fit well.

samdark on 1 Apr 2018

👍1

I read the whole thread, I do not understand why you can not recover the name of yii, and launch a 3.0 branch, and the extensions depending on the compatible version can be called yii2, yii3, yii4, yii5, as it happens with ionic, which moved ionic v1 to repo ionic-v1, at some point because of the technological changes there may be a BC, totally normal, that's what the programming is about, sometimes wanting to maintain compatibility, we are tied to totally outdated programs, yii is a powerful, extensible and simple framework , this may be the opportunity to launch the brand that is really yii as the name of the framework and not yii2 that sounds more in the name of version.

Another thing we should not only think about those who already work in yii, but in the new programmers who want to try yii, actually it is really difficult to configure the composer.json with the versions of 2.0 and 2.1, sometimes but we know we see extensions with branch 2.1 which are actually patches 2.0, is the opportunity to clean everything with yii 3.0, it's just my two cents.

tecnoterabyte on 1 Jun 2018

👍1

why you can not recover the name of yii

It is already used by a guy who's developing private projects.

We're going to use yiisoft/framework.

samdark on 1 Jun 2018

👍2

Why not use yiisoft/yii, and create a branch for each version, 1, 2, 3, ,4 ... ??, so it works ionic and it goes very well

tecnoterabyte on 1 Jun 2018

Because it's taken by Yii 1.1 already and requires rather complicated subsplitting. @SilverFire tried that already.

samdark on 1 Jun 2018

Yepp. You can see it in https://github.com/peesoft :)

SilverFire on 1 Jun 2018

@samdark @SilverFire Thks, although I know that many opposed the solution that made ionic was to move the v1 branch to a repository called ionic-team/ionic-v1 and they left the ionic-team/ionic repository for its branch v3 and development and they did not sacrifice the brand, and I can attest that ionic-v1 you have thousands of installations.

tecnoterabyte on 1 Jun 2018

Since there is a 3.0 branch and decision seems to have been made, can someone summarize what we actually gain from this change? I'm still not seeing any actual benefits from this. Yii does not follow semver (even if you remove fixed 2.) so you still cannot use ^ operator reliably. If core issue is not fixed by this, what is fixed by this change?

rob006 on 13 Jun 2018

Yii does now follow SemVer.

samdark on 14 Jun 2018

👍6 ❤3 🎉1

I know that, I wrote it myself in my comment. :) But when you look at the first post here the problem is that you cannot use ^2.0.15.2 as a constraint. But after releasing 2.1 a 3.0 you still cannot use ^ in constraint - ^2.15.2 is unsafe, since version 2.16.0 may bring BC break. So if core issue was not fixed, what is the reason of the whole mess - renaming version, repos and dropping well known and established convention of using yii2- as a prefix for Yii 2 extensions?

rob006 on 14 Jun 2018

👍1

It's SemVer since 3.0.0. 2.0.x is versioned as is.

samdark on 14 Jun 2018

❤3

Honestly, I don't believe that Yii 3 will actually use semver and I expect multiple obvious BC breaks in 3.X.0 releases "because it probably will not break your app".

I think that we have focused on the wrong thing. The problem is not versioning scheme, but versioning policy. Right now there is no stable line, not mention LTS. There is no constraint for people, that wants only bugfixes for their stable app. Upgrading from 2.0.12 to 2.0.13 may fix some bugs, but it also brings new features and new bugs/BC breaks. Then you need to wait another few months for 2.0.14 which will do the same - bring new bugfixes, and additionally (unwanted) new features and new bugs. Yii simply does not have enough resources to support semver.

I suggest to use "PHP versioning" with versions like 2.X.Y, where:

2 is fixed and will be changed only on some massive rewrite of Yii.
X for a major and BC break release - all big changes goes here. We should release it more frequently - once 6-12 months with small batches of BC breaks.
Y for patch release, with 100% BC promise. Here we have only minor features and bugfixes which cannot break BC. We could release it every 1-2 weeks.

Pros

Framework development should be faster since BC will not slow down us that much. Yii 2.0.0 was released almost 4 years ago and 2.1.0/3.0.0 has "36% complete". We probably need to wait at least 5 years between major releases - this is insane!
Upgrading to new major release should be easier since single release should have less BC breaking changes. Changes in 2.1/3.0 are already quite big and upgrading may be hard, and this is only "36% complete". Upgrading in small steps is easier.
Deliver bugfixes faster - you don't need to wait 3 months to complete 2.0.X milestone with its 200 issues.
We finally have the stable branch with BC promise.
It is easy to create LTS line - it may be 2.1.X (or any 2.X.line) with longer support.
Composer constraints are easy - just use ~2.1.11 or ~2.0.14 || ~2.1.0 and you will get both bugfixes and BC.
No need to rename repos, versions and dropping yii2- prefix convention.

Cons

Some potential BC breaking features may need to wait longer to release. This is the cost of stability.

rob006 on 14 Jun 2018

@samdark I saw that core extensions get upgraded to yiisoft/yii2: 3.x - will this stay or will there be another repo like yiisoft/framework?
Honestly, I'd keep it like it is now. We can also still use the yii2- prefix and people seem to easily adopt it.
Is 2.1 and 3.0 more or less the same thing?

@rob006 You have valid points about LTS and so on, but - still - with semver it's much easier to indicate breaking changes - and also to release patches more often (without using 4-digits).

schmunk42 on 15 Jun 2018

@schmunk42 Releasing patches using 4-digits is just as easy as with 3-digits - removing fixed 2. will nothing change in this matter. And yet patch releases are rare. I don't think we have resources to handle patch releases and minor releases simultaneously and work at major release at the same time. Just look how it works now - we have a 1-2 hotfix patch releases, then silent for few months for new minor release. And we still didn't get a major release. So patch releases are rare, minor releases are rare, and major releases are super rare. This creates huge gaps between accepting PR and actually releasing it. I may fix some bug today in PR, and I will need to wait like 3 months until it goes to the official release. Changing versioning scheme will not change any actual problem, and fixing the actual problem does not require changing versioning scheme.

rob006 on 15 Jun 2018

BTW: Laravel uses this approach - right now it has fixed 5., 5.X.0 for major releases with BC breaking changes and 5.5.X for BC patch/feature releases.

rob006 on 15 Jun 2018

@schmunk42 there will be no 2.1. 2.1 is the same as 3.0. It's kept there because some teams we know use 2.1 in production and they need some time to switch to 3.0.

Another repo is possible. Likely yiisoft/framework. Haven't fully tested moving things yet. Maybe we'll stay with yiisoft/yii2.

@rob006 we see no sense in keeping current versioning scheme. It's not what majority Composer packages use.

You're right that SemVer won't change actual release schedule much but at least it brings more transparency about breaking changes and corresponding release policy.

samdark on 17 Jun 2018

You're right that SemVer won't change actual release schedule much but at least it brings more transparency about breaking changes and corresponding release policy.

If Yii will keep current versioning policy and continue to introducing BC breaking changes in minor releases (like adding new method to interface or changing methods/classes behavior), then this is only a pretending that Yii follows semver, which is even more confusing. And it will still not fix major problems: missing "stable" line and too slow progress because of rare major releases.

rob006 on 17 Jun 2018

Rare major releases are not a sign of slow progress, it's a sign of stability. It would be absolutely great if we can keep this cycle at 3-4 years.

The old versioning policy pretended that there were only patch releases, but they often included more. And there were actually no patch releases at all, just security hotfixes if there was no other choice.

But I agree that there is much room for improvement about release cycles and BC. So patch releases should never break existing application, but another question is if there can be a planned release cycle for minor releases or if we should simply increment the minor version when there are changes which would require it. An example would be the changes mentioned in https://github.com/yiisoft/yii2/issues/15983#issuecomment-376506891 - technically this is BC and well-coded apps and extensions don't have an issue with it, but if there's a chance of breaking something ... increment the minor version.

schmunk42 on 17 Jun 2018

Rare major releases are not a sign of slow progress, it's a sign of stability. It would be absolutely great if we can keep this cycle at 3-4 years.

I'm not saying that this is the sign, but this is the reason. We have a 2018, middlewares are standard, but not in Yii. Most of important PSRs are not adopted in Yii 2.0, because it will require BC break. So we're waiting another year, maybe two to catchup 1-2 year old standards in Yii 3.0. Yii slowly becomes outdated - PHP word is going to interoperability, but Yii still have its own world and it is incompatible with anything else.

And we could talk about stability if minor releases would keep BC. But it's not. There is no stable line for Yii, we're breaking BC constantly, but not in way that could change something important and make Yii more modern. I would say that this is the worst possible scenario...

rob006 on 17 Jun 2018

@rob006 we'll actually try following SemVer. Also going to tag major releases more often after 3.0.0 initial release.

samdark on 17 Jun 2018

The only thing that's missing is enough time to handle all that so if anyone is stepping up as release manager tagging and announcing releases constantly that would be great.

samdark on 17 Jun 2018

👍1

@samdark That's why I proposed simplifying release cycle to only major (2.x.0) and patch (2.1.x) releases. If we don't have enough time to support three lines, then maybe we will have enough time to support two lines.

rob006 on 17 Jun 2018

👍1

It's simple enough in both cases. We don't have to support three lines except security (same as we do now). We'll just name versions differently and try not to break BC in minor releases and patches. That's it about switching to SemVer.

samdark on 17 Jun 2018

We don't have to support three lines except security (same as we do now).

Not really. I have a ~dozen simple apps/microservices in Yii2 which are basically finished and does not require much work. But maintaining them is annoying, because there is no stable/LTS branch for Yii. If new bug is reported, and this is a Yii bug, I need to upgrade to new minor (2.0.X) release to get this bugfix. And most likely something other will be broken by this. I would love to to see some LTS branch for Yii with BC bugfixes only. Right now there is not even a official branch for security fixes.

rob006 on 17 Jun 2018

Following or not following SemVer won't solve that.

Having someone interested who'll make releases and merge fixes back and forth could.

samdark on 17 Jun 2018

We could also have a release cycle that will not require this extra time and extra merges to/from two additional branches. I could help with that, but not with current release cycle - supporting LTS branch will require too much time with it.

rob006 on 17 Jun 2018

There's not a big difference. Noone forces us to maintain all possible variations of major and minor releases.

samdark on 18 Jun 2018

Some ideas to improve the process...

GitFlow-like policies
- BC-compatible changes go on master
- BC-breaking changes go on develop
- master is regularly merged into develop
- security fixes can be instantly released using a hotfix/... branch, based on the last release(s)
using (also) labels and github-bot to indicate in which branch a MR has to go
indicate LTS versions with metadata 3.0+lts (not sure if this can be required in composer.json, but it would be very nice, because you won't be able to upgrade to 3.1 if it is non-LTS
A good example: https://www.elastic.co/support/eol
- Support latest minor release from previous major until next major
- As Yii example: 2.0+lts is maintained until 4.0 is released, ie. 3.4.5 is then the base for the next LTS.
create -beta releases more often (without having to worry about the whole release cycle); developers could test upgrades much more easier and report errors before a stable release
[edit] create a 2.1+lts for latest stable version

schmunk42 on 18 Jun 2018

master-develop flow is really annoying for dependencies - it is not clear which branch points to which version, and PRs merged to develop are not counted as contributions by GitHub (unless we make develop branch default on GitHub). There are already well known and established standards for this, just look how Symfony or Laravel handling it. There is no need to reinvent the whole convention.

rob006 on 18 Jun 2018

master-develop flow is really annoying for dependencies

You mean for requiring Yii from dependencies?

it is not clear which branch points to which version,

Branches don't really point to versions IMO.

and PRs merged to develop are not counted as contributions by GitHub (unless we make develop branch default on GitHub).

Why shouldn't they count when the changes from develop make it to master?

There are already well known and established standards for this, just look how Symfony or Laravel handling it. There is no need to reinvent the whole convention.

Could you post a link for those guidelines?

schmunk42 on 18 Jun 2018

You mean for requiring Yii from dependencies?

I mean "go to Github repo and check code of 3.0 line". It is much harder if 3.0 line is in develop branch. Or master maybe? Lets check all branches to find what I want! \o/

Branches don't really point to versions IMO.

They're point to lines, and usually this is what you're requiring from composer (you're using 2.0.* as a constraint, not 2.0.15.1). I can use 3.0.x-dev to use unstable 3.0 line from 3.0 branch.

Why shouldn't they count when the changes from develop make it to master?

You cannot merge develop to master on daily basis - this will break BC. You can do this only on major release. Once per 2 years? :D

Could you post a link for those guidelines?

https://symfony.com/doc/current/contributing/community/releases.html

It is really simple - master is for main line (3.0 in our case) and all other old branches are named like 2.0, 2.1. After releasing 3.0.0 master is copied as 3.0 branch and master is now 3.1 line. At any point you may merge any contribution to master - if 2.0 needs a security fix, we may merge 2.0 -> 3.0 -> master, so master contains all changes from all previous branches. No LTS suffixes in tag or branch names - it only breaks version parsing.

rob006 on 18 Jun 2018

I don't see how the first two points would be in any way easier to handle if we would follow the old-versioning scheme. And the Symfony document doesn't describe how they handle their merging and branching policies. It also contains strange policies like:

In Symfony 2.x branch, the number of minor versions wasn't constrained, so that branch ended up with nine minor versions (from 2.0 to 2.8). Starting from 3.x branch, the number of minor versions is limited to five (from X.0 to X.4).

You cannot merge develop to master on daily basis - this will break BC. You can do this only on major release. Once per 2 years? :D

No, on release of a new minor version.

schmunk42 on 18 Jun 2018

No, on release of a new minor version.

You wrote:

BC-breaking changes go on develop

Do you want to introduce BC breaks in minor release?

And I'm not sure what do you mean by "old-versioning scheme" and what is strange in Symfony policies - they look pretty straightforward for me.

rob006 on 18 Jun 2018

Do you want to introduce BC breaks in minor release?

No, branching and defnition needs refinement here. I meant if there's a greater than 0% chance that it will break existing apps or https://semver.org/#spec-item-7 - I know you can't always get that perfectly.

what is strange in Symfony policies

The part I've mentioned.
They are also not that much different to what I've linked from Elastic.

But I also don't find them perfect, eg. the part with minor versions - I would not put that on a 6-month cycle.
If it happens it happens. If you care that much about it use ~3.1.1 as your constraint or stay on ~2.1.0+lts.
Major versions always have a more longterm process before they are released.

schmunk42 on 18 Jun 2018

Symfony policies work well with SemVer. That is what they use.

samdark on 18 Jun 2018

Symfony policies work well with SemVer. That is what they use.

Surely they work with SemVer, but it'd still not take them 1:1 - ie. around 1.1.2018 they have to maintain six versions (2.7, 2.8, 3.3, 3.4, 4.0, 4.1) - according to their graph.

schmunk42 on 18 Jun 2018

How many versions to maintain is a separate decision that is not connected to using or not using SemVer.

samdark on 18 Jun 2018

Since announcement made and decision is there, closing the issue. We'll get back to release frequency and policies when we'll release 1st 3.0.0. Meanwhile, if anyone feels like able to handle tagging releases and writing announcements, let me know. I'll gladly grant permissions necessary.

samdark on 18 Jun 2018

👍2

Yii2: Switch to plain semver (three version digits)

What steps will reproduce the problem?

What is the expected result?

What do you get instead?

Additional info

Tasks

Most helpful comment

All 125 comments

Why is Yii not simply using semver?

Pros

Cons

Related issues