Consider using Semver

[creocoder]

@qiangxue Is there any reason project not follow Semantic Versioning?

[samdark]

Quoting @qiangxue from https://github.com/yiisoft/yii2/issues/7529#issuecomment-77016695:

@creocoder We discussed about semver internally long time ago. Our current versioning strategy can be described as this, https://github.com/jonathanong/ferver, which we considered is more practical and reasonable.

Also, ideally we hope we can have a shorter release cycle so that issues like this can be fixed sooner than later. Unfortunately, currently we are relying on git subsplit, which is a very time-consuming process (it takes 8+ hours) when we have to make a release.

[samdark]

I'm not against sticking to semver but the real issue is about how long it takes to make a release. Personally I don't see any difference until release means just adding a tag.

[qiangxue]

For whom? At the current time, the use of exotic versioning approaches make Yii "black sheep" among all other PHP packages (which majority follow SemVer novadays). This require specific composer requre rules for Yii which differs from 100% safe rules for other packages. Simple example. I can use "leagule/flysystem:~1.0" inside composer.json and never have any headache with it. Its about trust. I can't use "yiisoft/yii:~2.0", i ever can't have "yiisoft/yii:~2.0.0" and last investigations show that only one reliable variation is "yiisoft/yii:2.0.2", so concrette version here.

@creocoder Once again, please try not to exaggerate things in order to convince people. SF is a clear example not following semver either. And jQuery is yet another major one. And there are many more out there.

I agree with you it's important to keep the versioning system trustable. Within the core developer team, we have emphasized several times that it is important to keep 2.0.x releases 100% BC-compatible. But this is an ideal plan. The ferver article has given out a real world example that this is hard to achieve in practice, regardless you are using semver or not.

In summary, our versioning policy is as follows:

• 2.0.x: patch releases, which should be 100% BC-compatible. Ideally, we hope they contain bug fixes only so that it reduces the chance of breaking BC. Practically, since 2.0.x is released more frequently, we are also adding minor features to it so that users can enjoy them earlier. Currently we are doing this once every two months.
• 2.y.0: BC-breaking releases, which contains major features and changes that may break BC. Upgrading from earlier versions may not be trivial, but a complete upgrade guide or even script will be available. We expect this to happen once every year or even shorter.
• z.0.0: major release. It's like 2.0 over 1.0. We expect this only happens every 3 to 5 years, depending on external technology advancement (such as PHP upgraded from 5.0 to 5.4).

Following this versioning policy, in future we may consider introducing 2.0.0.x as pure bug fix patch releases, while 2.0.y as minor feature enhancement releases. The former has a much shorter release cycle, (say a few days depending on when bugs are found and fixed.), while the latter will be more like the current 2.0.x releases. This largely relies on the availability of an automatic releasing system so that we can release 2.0.0.x more easily and frequently.

[qiangxue]

If you still want to insist on semver, then you may view the version prefix 2. in 2.x.y.z as part of the product name. Then you will get x.y.z which follows semver (currently we are using x.y only as explained above.)

[brandonkelly]

There are some very valid reasons against using SemVer. This article sums it up pretty well: https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e (via a @dhh tweet).

[cebe]

@qiangxue I have updated the versioning info docs with some text from your answer.

[creocoder]

@qiangxue Its wonderful suggestion

If you still want to insist on semver, then you may view the version prefix 2. in 2.x.y.z as part of the product name. Then you will get x.y.z which follows semver (currently we are using x.y only as explained above.)

Unfortunately way of seeing does not fix current and more important future versioning drawbacks:

• you can't use ~2.0 to get fw and ensure everything will be fine (there is many packages and at least 1 framework in php world where you can be sure)
• when you do composer requre yiisoft/yii2 without using concrette version it assumes that package use semver and will add ~x.y to require section automatically (you can see that as SemVer become some standart and sign of quality)
• lets imagine 2.1 is out and this is non BC, do you see what will happen inside Yii 2 extensions world? I see 2 different ways will happen and both is like you need to choose between bad solution and very bad solution.

and mainest thing about:

• using ferver give end user nothing except additional issues

z.0.0: major release. It's like 2.0 over 1.0. We expect this only happens every 3 to 5 years

Its too slow for novadays php world. Consequences which will result in such a policy is a topic for another discussion... IMO very sad discussion.

P.S. SemVer is not super critical thing, but not using that is objectivelly drawback. Yes, using SemVer requires a different level of design and responsibility. I do not propose to enter it now. I propose forget about 2.1 and skip this version in favour of 3.0 from which start follow SemVer strictly.

[qiangxue]

you can't use ~2.0 to get fw and ensure everything will be fine (there is many packages and at least 1 framework in php world where you can be sure)

Use ~2.0.0, ~2.1.0, etc. I don't consider this as a drawback at all other than that it is not following semver.

when you do composer requre yiisoft/yii2 without using concrette version it assumes that package use semver and will add ~x.y to require section automatically (you can see that as SemVer become some standart and sign of quality)

This is an imagined use case. And even if it really happens, it is an easy fix. Again, please do not make your personal opinion sound like a public one. semver and quality are different things. There are many high-quality projects in this world that do not follow semver.

lets imagine 2.1 is out and this is non BC, do you see what will happen inside Yii 2 extensions world? I see 2 different ways will happen and both is like you need to choose between bad solution and very bad solution.

I don't get what is the problem.

Its too slow for novadays php world. Consequences which will result in such a policy is a topic for another discussion... IMO very sad discussion.

I don't know how you come up with this conclusion. Yii 1 to 2 is like SF 1 to 2 or ZF 2 to 3. They all take very significant effort to develop. If you are referring to Laravel, then from Yii 2.0 to 2.1 is like Laravel 4 to 5. It's not slow at all.

I propose forget about 2.1 and skip this version in favour of 3.0 from which start follow SemVer strictly.

Nope, we will stick to our versioning policy as described above. Introducing 3.0, 4.0, etc. is only theoretically sounding for Yii. In practice, it will cause a lot of confusion.

[creocoder]

@qiangxue

If you are referring to Laravel, then from Yii 2.0 to 2.1 is like Laravel 4 to 5. It's not slow at all.

Laravel release major version is 1 year.

I don't get what is the problem.

Ok, lets imagine 2.1 out. As i understand we follow LTS support, even if 2.1 out 2.0 will be supported, right? Ok, now look into extensions world. Extensions named like yii2-extension-name. Developing new extension version for 2.1 inside same repo mean automatically stop support for 2.0 version. I do not think extensions developers will go that way (at least i will not go, still thinking about best strategy). If Yii 3.0 out everything is simple just make new repo yii3-extension-name, continue support yii2-extension-name whole 2.0 LTS cycle and everybody will be happy. Now realize 2.1 out. There is two ways: continue developing extensions inside yii2-extension-name repos. One devs will go that way. Create new yii2.1-extension-name reso which looks ugly and some developers will go that way because of LTS for 2.0 and its extensions (at least if you good extension dev). This will lead to schism among extension developers. Which is not good and to be honest this is only aspect i care about.

Nope, we will stick to our versioning policy as described above. Introducing 3.0, 4.0, etc. is only theoretically sounding for Yii. In practice, it will cause a lot of confusion.

Its OK, i'm personally can live with that. How to be with extensions?

[cebe]

why do you think all extensions need a new repo? If we go from 2.0 to 2.1 we will keep most of the things compatible, this is not like the switch from 1.0 to 2.0. Most extensions will still work and if they will not they can open a branch too and maintain two versions with slight adustments for 2.0 and 2.1. These dependencies and compatibilities can be easily reflrected in composer.json.

[qiangxue]

Laravel release major version is 1 year.

Yes, that's exactly similar to what we plan for 2.x releases, except we are using 2.X for release vehicles instead of X.0.

Developing new extension version for 2.1 inside same repo mean automatically stop support for 2.0 version.

How comes? The extension should have a branch supporting 2.0, and another branch supporting 2.1, and so on. It will be similar to the yii2 branch layout.

[qiangxue]

@creocoder Really, there's no fundamental difference between our version policy and semver. The only difference is we are using a 2. prefix to all version numbers.

[creocoder]

How comes? The extension should have a branch supporting 2.0, and another branch supporting 2.1, and so on. It will be similar to the yii2 branch layout.

If Yii does not support SemVer, OK. But not following SemVer mean dead for small php libraries :) This is why separating branch not works here. If take into account

If we go from 2.0 to 2.1 we will keep most of the things compatible

Its probably fine. But you can't release new non BC extension versions after 2.1 out. Ok, lets check real word example. For example theoretically we decide to cut out behaviors in favour of traits in 2.1.

Now consider case:

yii2-taggable 0.1.0
yii2-taggable 0.1.1
yii2-taggable 1.0.0
yii2-taggable 2.0.0 // yes I have ultra cool idea here and i break BC!
yii2-taggable 3.0.0 // here is also some revolutionary idea and BC was broken again!

Now realize Yii 2.1 out. This automatically mean that continue development inside same repo mean that you can't more release non BC version. Same way you can release non BC versions for 2.1... So without new repo evolution for 2.0 extension version will be stopped.

If we go from 2.0 to 2.1 we will keep most of the things compatible

This is bad news... So no plans about fixing many architectural errors, etc? Many things can be fixed only with total BC break. But following SemVer give possibility to break every aspect in 3 version for example. This is not an advantage?

[qiangxue]

I still don't understand your reasoning. Your example has nothing to do with semver at all.

You misunderstand @cebe's words. BC may be broken between 2.X releases, although we may try not to break too much.

[creocoder]

I still don't understand your reasoning. Your example has nothing to do with semver at all.

My example is strict following SemVer. My users have 100% garantee from me that nothing will be broken if they use SemVer for extensions inside their composer requirements. So for example you can use ~1.0 and then when you decide and have time you can upgrade to ~2.0 and even if for 2.0 i'll make 100 minor and 1000 patch updates i garantee that BC will not be breaked. If i break BC i just make new version out. Now realize 2.1 out. I'm not sure i do not want release not BC versions for 2.0 in parallel with 2.1.

So in future it may lead to:

yii2-taggable 3.0.1
yii2-taggable 3.1.0
yii2-taggable 3.1.2
yii2-taggable 3.1.3

I can't make

yii2-taggable 4.0.0

for 2.0 users. On other side i can release any versions for 2.1 since it version counter begin from start:

yii2.1-taggable 0.1.0
yii2.1-taggable 1.0.0

[creocoder]

@qiangxue I just want to say that it is unfair to 2.0 users. This is why branch idea is not acceptable. On other side i cleanly see that some extensions developers will choose branches, but some never. You can look at this schism in Laravel world. There is extensions named like laravel-extension, there is extensions named like laravel4-extension, laravel5-extension. I do not want such schism for Yii world, because its clean for me that all extensions which decide go branches way will be dead.

[qiangxue]

Ok, assume Yii is using semver and we are releasing Yii 3.0 which drops behavior in favor of trait. What will happen to your extension?

[creocoder]

@qiangxue Simple. I'll make

yii3-taggable 0.1.0

But when after month i'll have new idea which can be implemented inside behavior and inside trait i'll make

yii2-taggable 2.1.0

and 

yii3-taggable 0.2.0

And will support yii2-taggable as long as you'll support 2.0 in parallel with 3.0 version. This is where big numbers work great. And this is where SemVer give some misc cosmetic advantages.

[qiangxue]

So you are mainly complaining about the naming of extensions? Why yii2-taggable-new won't work? You have full freedom to name your totally new versions.

On the other hand, I also want to point out a major problem with semver. Imagine we are releasing 1.0, 2.0, ...all the way to 50.0. Some major releases are very significant, just like yii2 vs yii1. As a user of Yii, I'm fine adjusting minor BC breaks, but not the major one like yii2 over yii1 because it requires me to rewrite my app. Can you tell me how semver would solve this problem?

[creocoder]

@qiangxue On other side if Yii will out as 2.1 it will possible lead me to solution like:

yii2-taggable 3.0.0 // 2.1 version

Here you can see how fw versioning insist on extension developer decisions even if he do not want it. Also all we remember that Yii 2 was alpha, beta, etc. Going new yii3-extension-name repo also give extension developer some freedom to play with design and decisions inside 0.y.z version and make 1.0.0 as stable as possible. This is why goind branch is bad idea always.

I also want to point out a major problem with semver. Imagine we are releasing 1.0, 2.0, ...all the way to 50.0... Can you tell me how semver would solve this problem?

YES! And SemVer document have clean answer to that! Look

If even the tiniest backwards incompatible changes to the public API require a major version bump, won't I end up at version 42.0.0 very rapidly?

This is a question of responsible development and foresight. Incompatible changes should not be introduced lightly to software that has a lot of dependent code. The cost that must be incurred to upgrade can be significant. Having to bump major versions to release incompatible changes means you'll think through the impact of your changes, and evaluate the cost/benefit ratio involved.

[qiangxue]

YES! And SemVer document have clean answer to that! Look

Nope, I'm not complaining about the high version number. Let's say Yii 5.0 over Yii 4.0 is like Yii 2.0 to Yii 1.1. As a user, I don't want to upgrade from 4.0 to 5.0 for obvious reason. How can I keep using Yii with new releases that only introduce minor BC-breaking changes?

[qiangxue]

Regarding your extension naming proposal, it also has a drawback. Assume you name your extension to be yii2-taggable. Does it support yii 3 or not if it is not affected by the change from yii 2.0 to 3.0? If no, it means you have to create a new extension yii3-taggable, which is a trouble because as an extension author I may not want to track all major releases. If yes, then it's clearly very confusing by its name.

[creocoder]

So you are mainly complaining about the naming of extensions? Why yii2-taggable-new won't work? You have full freedom to name your totally new versions.

This is right. And this is most horrible thing here. This will lead to mess inside extensions world. Some people will have their extensions like yii2.1-extension-name, other people will make new branches and support new extension versions inside yii2-extension-name. Some other people will use something like yii2-taggable-new... For me personally i decide that extension naming should follow strict rules.

Nope, I'm not complaining about the high version number. Let's say Yii 5.0 over Yii 4.0 is like Yii 2.0 to Yii 1.1. As a user, I don't want to upgrade from 4.0 to 5.0 for obvious reason. How can I keep using Yii with new releases that only introduce minor BC-breaking changes?

In that case frameworks usually go "branch like versions names" way. You can have 4.x branch and 5.x branch. So you can not break BC inside 4.x or 5.x. This is why i said following SemVer is another level of fw design and responsibility. And this is why release cycle is less than 3 - 5 years.

Assume you name your extension to be yii2-taggable. Does it support yii 3 or not if it is not affected by the change from yii 2.0 to 3.0? If no, it means you have to create a new extension yii3-taggable, which is a trouble because as an extension author I may not want to track all major releases.

Fantastic situation ) Really. Did not saw such things inside extensions. If even it teoretically possible it very rare case.

[creocoder]

@qiangxue But we can solve all troubles absoluttely different level. If we write inside Guide some rules how to deal with 2.1 version for existent extensions and officially stop possible mess i'm fine with any proposal around it (new repos, new branches, stop 2.0 users support, etc).

Currently Yii 2 extensions world is cool and consistent. Everything live inside yii2- prefix repos, pedantic users happy. I just try to prevent possible troubles in that world, even if it require insist on following SemVer. I'm fine with FerVer with some Guide explainations about extensions developers strategy.

[qiangxue]

In that case frameworks usually go "branch like versions names" way. You can have 4.x branch and 5.x branch. So you can not break BC inside 4.x or 5.x. This is why i said following SemVer is another level of fw design and responsibility. And this is why release cycle is less than 3 - 5 years.

Then you are breaking your own semver rule because you are now introducing BC-breaking changes in 4.x releases. Also, it's very hard for users to catch the significant difference between between 4.0 and 5.0, especially if you have very high version number.

Fantastic situation ) Really. Did not saw such things inside extensions. If even it teoretically possible it very rare case.

How comes this is rare? This happens to ALL extensions that are not affected by the major version changes. This is much more common than your example (in your example you are assuming an extension's code base should be completely replaced, which is very very rare).

[creocoder]

Then you are breaking your own semver rule because you are now introducing BC-breaking changes in 4.x releases. Also, it's very hard for users to catch the significant difference between between 4.0 and 5.0, especially if you have very high version number.

Hmm seems i misunderstood your question than. But OK. Lets check how it work on real world example. For example we decide made new framework. We create:

cool-framework 1.0.0
cool-framework 1.0.1
cool-framework 1.0.2
cool-framework 1.1.0
cool-framework 1.2.0

No BC breaks at all inside 1.x. We have lot of experiments with design and api onside 0.y.z versions. After year it grow to 1.12.0 for example. Now you decide make 2.0 version which complettely break BC:

cool-framework 2.0.0
cool-framework 2.0.1
cool-framework 2.0.2

You can make new BC (with 1.x) features inside 1.x branch and out new 1.x.z versions. You can make new BC (with 2.x) features inside 2.x branch and out new 2.x.z versions. So I do not quite understand where the problem is.

P.S. But as i said before 2.1 is fine with good Guide adition about extensions developers strategy recomendations.

[qiangxue]

Nope, your example doesn't explain my problem. I am saying this:

• version 1.x: all fine
• version 2.x: small BC-breaking changes. I'm fine since I'm willing to take the trouble to upgrade so that I can get the new cool features.
• version 3.x: major BC-breaking changes (it's like yii2 vs. yii1.1). I don't want to upgrade to this version because it requires me to rewrite my app almost completely.

Now once 3.x is out, does it mean no more BC-breaking changes can be made on top of 2.x? Note that since 2.x could potentially have a huge user base, you certainly cannot require all of them to turn to 3.x. How would you continue your support for 2.x? Is it really realistic that you will be able to not introduce any BC-breaking changes over 2.x?

[creocoder]

Is it really realistic that you will be able to not introduce any BC-breaking changes over 2.x?

Yes, you can continue support 2.x in non BC breaking mode. But SemVer does not accept any BC breaking changes inside 2.x from start of 2.0.0. So when you decide introduce 3.x you already work some time with 2.x and somehow non break BC there. How 3.x will affect that you'll want introduce even small BC break changes inside 2.x?

On other hands there is lot of positive experience with force your own user base to upgrate to new versions. Some guy which name start from T does not have any troubles with that :) Yes some people complain, but its minority of people, majority is happy.

[qiangxue]

On other hands there is lot of positive experience with force your own user base to upgrate to new versions.

Just imagine a CMS based on Yii 1.1, and the CMS has a lot of extended versions. It's easy to say we should force the upgrade.

[creocoder]

Just imagine a CMS based on Yii 1.1, and the CMS has a lot of extended versions. It's easy to say we should force the upgrade.

Lets be honest. CMS way is different from frameworks way. There is lot of examples in past with it. For example Drupal. What make CMS good? Its extensions developers. Right? CMS core is usually small. If you'll stuck for long time on Yii 1.1 for example when 2.0 is already half or more year out this will cause some complains inside extensions developers sphere. So LTS or not for 1.1 when there is new stable fw version is not only one aspect of upgrading. Sometimes you need upgrate to new version by different reasons. And real world cleanly show that only projects which ready to upgrate their app or projects any time is live and others is dead. This is if we talks about open source projects. If we talk about 1.1 sites for examples. Hmm... Sites can live with Yii 1.1.7 for example without loose anything. On other side if your site (commercial project) live from 1.1.7 times that mean you have money and resources to upgrade it to 2.0+. This not always necessary btw. Even stop fw support now always lead to upgrate. I know people who happy with Yii 1.1.16 and soooo happy that they do big eyes when i suggest upgrade to Yii 2 ) Upgrade or not upgrade is personal developer or businessmen decision. Main thing is "patch mode" is always possible with SemVer or FerVer.

[qiangxue]

Now you are finding excuses to solve the deficiency in semver. Not only just CMS, any other applications that are released to public installations have the same problem, simply because the upgrade cost is too significant for such version upgrade. Indeed, I'm very honest about this issue because we have several huge apps based on 1.1 which we simply don't want to take time to rewrite them on 2.0 (even if I'm the expert of 2.0) and would still want to continue enhancing and developing them.

There are also environment requirement issues. Imagine we now start to develop Yii 3.0 on top of PHP 5.7. At the same time, we still want to maintain Yii 2.x simply because its environment requirement PHP 5.4 fits the majority of users. Does this mean we can no longer make BC-breaking releases for PHP 5.4 environment once we release 3.0?

[creocoder]

Now you are finding excuses to solve the deficiency in semver. Not only just CMS, any other applications that are released to public installations have the same problem, simply because the upgrade cost is too significant for such version upgrade. Indeed, I'm very honest about this issue because we have several huge apps based on 1.1 which we simply don't want to take time to rewrite them on 2.0 (even if I'm the expert of 2.0) and would still want to continue enhancing and developing them.

Than i have question. Do you really think that 1.1.7 to 1.1.16 was really necessary progress? Do not you think that dropping support and enter the patch mode at version 1.1.7 probably will gave better results now (i mean novadays). People can live with 1.1.7. On other side lot of time would be win for another version with necessary BC breaks and necessary design changes.

I'm personally calculate that support Yii 1 project for year cost twice+ support same project on Yii 2. Upgrade for big projects usually === save money in perspective. This is just proof why T ideas about stop support and force works in real world.

There are also environment requirement issues. Imagine we now start to develop Yii 3.0 on top of PHP 5.7. At the same time, we still want to maintain Yii 2.x simply because its environment requirement PHP 5.4 fits the majority of users. Does this mean we can no longer make BC-breaking releases for PHP 5.4 environment once we release 3.0?

Times of shared hostings is gone. Users mostly can use any php versions now. Also i do not think that language version is sooo important. More important is object oriented design, philosophy, strict rules, community control and understanding their needs.

[qiangxue]

Do you really think that 1.1.7 to 1.1.16 was really necessary progress?

You are assuming an ideal world. The reality is that we have been spending our majority of time in 2.0 since 2012. However, users can't just wait for 2.0 without doing anything with 1.1. Just take a look even today many users are still requesting backporting 2.0 feature to 1.1.

Upgrade for big projects usually === save money in perspective.

That's your opinion, and definitely not 100% true. If my app already works very well and I am very comfortable working with 1.1, why should I spend time and money to rewrite it on 2.0?

Times of shared hostings is gone. Users mostly can use any php versions now. Also i do not think that language version is sooo important....

It's not just about PHP alone. It is also about PHP extension and other library support since many may not catch up with 7.0 release.

Anyway, to this end, it seems none of your arguments for semver hold. And as I explained many times, the only difference between our version policy and semver is that we are using a 2. prefix. I don't think that's a fundamental difference and we will continue using it to avoid introducing confusion. In fact, you may view our version policy as an extension to semver because we are using X.0.0 to represent major BC-breaking changes, x.Y.0 to represent minor BC-breaking changes, while semver doesn't differentiate them.

I'm closing this issue since we will not take action on changing the version policy.

[creocoder]

@qiangxue

I don't think that's a fundamental difference and we will continue using it to avoid introducing confusion.

I agree with that. I just ask to not forget Guide section with recomendations for extension developers about their actions when 2.1 is out. I'm personally think that going same repo yii2-extension-name is best option in that case. Also most yii 2 extensions developers go SemVer way for extensions. We need document that fact in Guide too and make it recomended way for extensions. So SemVer or not i mostly care about extensions destiny after new non BC version of Yii will out.

[solracsf]

Here is another explanation very close to the Yii versioning: http://build.prestashop.com/news/a-more-semantic-versioning-scheme/