Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

True Semantic Versioning #350

Closed
jpalawaga opened this Issue Jun 19, 2013 · 9 comments

Comments

Projects
None yet
6 participants

Does Guzzle ever plan to follow true semantic versioning?

The pace at which guzzle updates and breaks BC makes it hard to track guzzle updates to get the latest features and bug fixes.

symfony, for example, has commited to trying to not break BC, and is now being targeted by the community with ~2.x. It would be very handy to get the latest version of guzzle with bug fixes but not BC changes.

Owner

jeremeamia commented Jun 19, 2013

If by "true semantic versioning", you mean SemVer, then I'm not sure when/if Guzzle will change to that scheme. There is certainly some merit in switching to SemVer, but Guzzle has always adhered to a form of semantic versioning.

Essentially, the current versioning scheme works like this: For a given version number X.Y.Z, X represents fundamental or paradigm changes to the project, Y represents major changes or feature additions (possibly including backwards-incompatible changes), and Z represents minor changes and fixes that are backwards-compatible.

You can always check the UPGRADING doc for details as well.

The upgrading doc is fine, but I suppose the real issue is that it's very difficult to track the latest version of Guzzle because the interface breaks every 2 weeks.

Owner

jeremeamia commented Jun 19, 2013

I'm not proposing any solutions here, just sharing some observations.

There has been a lot of rapid development over the last year and TONS of user contributions as well. I somewhat agree with you that it is hard to keep up with the latest version.

I work on the AWS SDK for PHP, which is a major consumer of Guzzle. We have been able to keep up with the changes mainly because @mtdowling works with me on that project. Many of the changes to Guzzle from the late 2.x to now have been driven by the use cases of the AWS SDK for PHP, which have exposed missing features and bugs. We've made sure to add features and fixes back into the Guzzle project to benefit everyone.

I don't believe SemVer necessarily solves the problem you have identified. If Guzzle was using SemVer, then its major version would technically be somewhere in the late teens, I'd suspect. It wouldn't actually affect the number of changes that have occurred though.

It's great that all of the changes that AWS has brought along are getting filtered back into the public domain. Too often, source simply disappears or projects lose support.

I sort of reached the same conclusion you did at the end of my last post--it's not that Guzzle doesn't use SemVer properly (though, this would still be nice), it's just that the pace is very rapid and hard to track because of that.

Knowing the scheme that you have identified above, it would be easy enough to target 3.7.x (in the latest version case), instead of 3.x and not have BC breaks. The fact that Guzzle reserves a whole designator for 'fundamental or paradigm changes to the project' is a bit disconcerting, though.

Thanks for your insight. Perhaps you can lend some insight for people out there (myself included) as to when is the ideal time to upgrade Guzzle releases? Every two weeks just isn't feasible.

azogheb commented Jun 21, 2013

First of all - love Guzzle - for sure the most complete PHP HTTP client around!

A few points to bring up IRT this thread:

SemVer is a widely accepted defacto standard, it provides a shared language for developers wishing to share and distribute versioned and packaged software. There is little reason to not use SemVer. If this results in the Guzzle version being in the "teens", then so be it - at least users would be aware and able to plan for BC breaking changes.

@jeremeamia says: "We have been able to keep up with the changes mainly because @mtdowling works with me on that project. " - Unfortunately not every user of Guzzle has @mtdowling on their team, integrating the BC breaking changes and updates bi-weekly.

I concur with @Magzine statement: "Perhaps you can lend some insight for people out there (myself included) as to when is the ideal time to upgrade Guzzle releases? Every two weeks just isn't feasible."

As open source projects start to get traction and become used by more then the original creator, more care should be taken on how deprecations, renames, namespace changes, interface changes, changes in behaviour - anything in the public use API - may affect the community.

Other very large projects like Doctrine, Symfony2, Twig, Propel, etc all manage to make significant improvements, features, bug fixes, etc very frequently without major changes to the interface. Perhaps some learnings in terms of branching, planning, communication and versioning could be gleaned from these projects and brought back to Guzzle.

Perhaps @mtdowling can start to add the @api tag to denote what is promised to not change, much like what Symfony2 has done. http://symfony.com/doc/current/book/stable_api.html

Some of the BC breaking changes at times seem to be just made at a whim, for personal preference or just because its "better" - without regard for the downstream impact for client libraries.

I want to continue using Guzzle for years to come and not be forced to move on to somthing else or fork and not go back. The issues brought up in this thread need to be addressed in some way.

Owner

mtdowling commented Jun 23, 2013

Guzzle has been sort of emulating how Symfony2 has managed versioning. If you take a look at their changelog and upgrading guide, you can see that they introduce several breaking changes in every minor point release.

I've made some significant changes recently in 3.6 and 3.7. I wanted to lump these two releases together to have less of an impact, but wasn't able to do so due to time constraints. Because I was emulating Symfony2, one of the most popular PHP frameworks and something that's referenced in the comments of this issue, I did not bump the major version to 4.0.

Perhaps you can lend some insight for people out there (myself included) as to when is the ideal time to upgrade Guzzle releases?

You should upgrade to >= 3.7.

[..] Every two weeks just isn't feasible.

Like any other open source project, you don't have to upgrade with every release the moment it is released. If you are affected by a bug or need a feature that was introduced in a new version, then I say upgrade immediately. Otherwise, take however much time you need and upgrade when it's convenient to you.

Other very large projects like Doctrine, Symfony2, Twig, Propel, etc all manage to make significant improvements, features, bug fixes, etc very frequently without major changes to the interface.

WRT to Symfony, this isn't true as I stated earlier. However, maybe that's not the best model to follow.

Perhaps @mtdowling can start to add the @api tag to denote what is promised to not change, much like what Symfony2 has done. http://symfony.com/doc/current/book/stable_api.html

I don't like this idea. If you want me to go full on semver, then these annotations should not be needed and it should be implied that any public method has a @api tag.

Some of the BC breaking changes at times seem to be just made at a whim, for personal preference or just because its "better" - without regard for the downstream impact for client libraries.

Changes are never made on a whim. They are made to make the library better, faster, easier to understand, and more flexible.

As open source projects start to get traction and become used by more then the original creator, more care should be taken on how deprecations, renames, namespace changes, interface changes, changes in behaviour - anything in the public use API - may affect the community.

I'll try to be more vigilant in ensuring that changes are made without a BC impact. BC changes that have already been introduced cannot be undone. Going forward, however, I'll do a better job.

As for the pacing at which Guzzle releases occur-- I'm not going to slow down. Guzzle is evolving into a much larger project that has very demanding users. Bug fixes, new features, and performance improvement are going to be added to Guzzle on a regular basis. However, I'll do this in a manner in which does not incur any BC breaks, or if there are BC breaks, I will bump the major version.

Hopefully this response allays your concerns. I'll go ahead and resolve this issue, but feel free to continue the conversation on the Guzzle forums if there's more you'd like to discuss: https://groups.google.com/forum/?hl=en#!forum/guzzle

@mtdowling mtdowling closed this Jun 23, 2013

@mtdowling your statements about symfony are entirely correct, but do note SensioLab's pledge, "After the release of Symfony 2.3, backward compatibility will be kept at all cost". And, because of this, almost ALL community bundles AND internal symfony components now target symfony using the next-significant-release operator in Composer (~)--a committment to SemVer if I've ever heard one.

As much as I like Symfony, I don't agree with their previous instances of breaking BC between minor versions. But even so, Symfony BC breaks ended up being once every couple months at maximum, not every 2 weeks... and, even when the interface did change, it was generally not changes to symfony's core foundation.

Anyhow, thanks for your consideration on the matter. I'm sure that myself, @azogheb among many others would be grateful for a stable, consistent Guzzle that still manages to keep its status as the best PHP HTTP client.

Cheers!

nikcub commented Jul 24, 2013

@jeremeamia

If Guzzle was using SemVer, then its major version would technically be somewhere in the late teens, I'd suspect.

This problem isn't unique to Guzzle. The solution is to have a 'wip' (work in progress) branch marked as beta which allows you to release the big features as soon as they are developed but to not increment the top version number. eg.

4.0.0-beta
4.0.1-beta
4.0.2-beta

or -dev (which is more common in PHP and supported by software)

-rc1 and -rc2 are then used for bugfixes prior to the major point release

can all change interfaces and break backwards compatibility on each other since they are beta branches.

You need semver because php developers and package managers need a way to be able to ask for the latest bug fixes without breaking compatibility. For eg. a developer tells composer they want 3.7.* or 3.6.* and update automatically without the fear of breaking anything. Most package managers understand semver and understand this, it means you can run 'update' as frequently as possible and capture all security and bug updates to that version.

Hang on, beta != dev. These are two different things.

beta and RC are all stages of stable, and should be in feature freeze, meaning the API should not be changing.

A dev branch is just "where the next version" is coming from, so if its 4.x-dev or 4.0.x-dev then different rules will apply.

SemVer has rules for most of this, and the rest is gitflow and logic, but if somebody is switching around an API on -rc1 and -rc2 I'd have to suggest they might be doing it wrong.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment