Breaking change to listCse function in 0.130

[jedi58]

In 0.130 the listCse function has been changed from: public function listCse($q, $optParams = array()) to: public function listCse($optParams = array()) so is a breaking change with only a minor version number change

[jdpedrie]

This library contains auto-generated clients which map directly to the Google APIs. That means you can always use the latest version of the clients in your code without waiting for someone to manually update the clients, but it also means it's hard to control for breaking changes.

Outside of development, you should pin google/apiclient-services to a specific minor version, and not update that until you've verified that it works.

[jackbentley]

@jdpedrie Does this library use Semver?

This issue also seems similar to #190 (different area, same issue?)

[jdpedrie]

Yes in the technical sense that it is versioned pre-1.0, where breaking changes are allowed in minor versions.

[jackbentley]

Excellent, thanks. That does seem to make the change in line with Semver as you said then.

Would it be worth upping the version to v1 - as it does seem we've been on v0 for about 4 years now? Especially considering this library interfaces with live, stable, APIs - it's a bit misleading and doesn't infuse confidence or perceived reliability in the library?

[jdpedrie]

The advantage of pre-1.0 versions is that composer treats them like major versions.

For instance, if you require ^v0.1, composer will install v0.1.100000, but not v0.2.0. For pre-1.0 packages, composer assumes there may be breaking changes between minor versions.

Once a library reaches 1.0, composer starts assuming no breaking changes within major versions. That means that requiring ^v1.0 would install v1.2.0.

In practice for this library, we'd need to bump the major version with every release, since they are generated automatically. Since we've already established the pattern of minor versions, there's no real need to change it.

[jackbentley]

Thanks for the explanation. I've done some digging around as to why this ticket was raised. I think I've come up with why, but I'm not sure of the correct way to properly solve it.

I understand this is long, but some guidance would be appreciated.

It looks like the project that caused this issue to be raised didn't have google-api-php-client-services in its composer directly. Instead, it depended upon only google-api-php-client.

It looks like google-api-php-client requires google-api-php-client-services with a tilde (~) operator. Which unlike like caret (^), as you explained above, doesn't take into consideration the minor version potentially including breaking changes when the major is 0.

This meant that the project automatically received the version in which the breaking change occurred even though the requirement for the PHP client was correct.

I'm unsure if the project should be specifying both libraries or not? It could be argued that everything from the client services is considered the public API of the PHP client?

I'm not entirely sure on the architecture of the API clients; so, does the PHP client require the client services in order to provide it as an API or does it have an actual dependency on the code?

The reason for asking is that people could inadvertently be pulling in breaking changes if the code from google-api-php-client-services is considered to be part of the public API of google-api-php-client as they're unlikely to set a requirement of the client services in composer.

If it's the latter, then the project definitely should have been manually specifying google-api-php-client-services in its own composer. Arguably the PHP client should probably be updated to use a caret as you recommended here.

If it's the former, then the version of the client services and PHP client are directly linked. If there are breaking changes in the client services then this should be reflected in the major version of PHP client. Alternatively, the PHP client probably shouldn't include client services as a dependency to ensure that people pull in a version and are under the control of any potential breaking changes.

---

As for the 0 major version in this repo, this part of semver.org concerns me:

4. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Is this library considered stable? If my suspicions are correct, setting minimum-stability in composer to stable might prevent you from using the library entirely? If it doesn't I'd argue it should.

The FAQ section of semver.org is also interesting. I feel like this library hits most these points.

How do I know when to release 1.0.0?
If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

This is also interesting to consider:

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.

I personally don't see an issue with making the major version 126. It might be wise to make the auto-generation/tagging a bit smarter and consider if the API has changed or not before deciding if a major or minor or patch version should be applied.

I appreciate the versioning is kind of a tangent, so I'd be happy to open a new ticket about it if you'd like?

[jdpedrie]

I'm unsure if the project should be specifying both libraries or not?

Yes, that's the safest course. I opened googleapis/google-api-php-client#1823 to make this clearer in the documentation for the API client.

does the PHP client require the client services in order to provide it as an API or does it have an actual dependency on the code?

The former. google/apiclient doesn't call into google/apiclient-services. In this way the dependency tree is inverted.

If my suspicions are correct, setting minimum-stability in composer to stable might prevent you from using the library entirely?

It does not prevent installation. It would prevent you from installing dev-master, but not a pre-1.0 tag.

All your points are valid and are things we've been considering. The current situation is less than ideal and we're looking at ways we can practically improve it.

The proper way to solve it is to think of this repository as a snapshot of the state of Google APIs at a given point in time. Freeze that snapshot at the point when you develop against it.

Thanks for the research, you stated the issues very well. I opened #1823 to improve the documentation around this issue, and we'll keep working to improve the overall situation as well.