Version tags for versions before 3.4.0

[kylefleming]

Hi,

Can you add versions tags for versions 3.2.0, 3.2.1, 3.2.2, 3.2.3, 3.2.4, and 3.3.0? These versions of the CardIO library are installable through CocoaPods but are currently referenced by commit hashes, which we would like to convert over to using tags instead. Using tags to reference version numbers is important because it definitively indicates which commits belong to which version.

Here is an ongoing discussion regarding CardIO's presence in CocoaPods. CocoaPods/Specs@a318bf5

[josharian]

@GARTHEX thanks for bringing this to our attention. We'd like to do the right thing by CocoaPods; perhaps you can help us find a way to do this that also works with our constraints. Here are a few initial thoughts.

It is important to us to be able to remove old versions. Ceasing to distribute old versions is a common practice. This is particularly important when old releases contain known security issues. I'm not sure that CocoaPods is doing the right thing here by insisting on having them available. Would it help to add a line to our release notes/emails indicating what old versions are being removed when we publish a new version?

Note that we use semantic versioning, which means that upgrading should be entirely safe for non-major-version bumps. Locking into a particular card.io minor/patch version has very little value. Does CocoaPods support something like "most recent in the 3.x.x line?" instead of "3.2.3"?

One other sticking point is that the right way to distribute binaries like this is via GitHub Releases, not a git repo. We had it set up as a git repo, but only because at the time, GitHub Releases was not available. I don't know how CocoaPods interacts with GitHub Releases, but that's another open question to resolve.

[kylefleming]

@josharian Thanks for your quick response. I'll address these in reverse order.

CocoaPods handles GitHub Releases the way it would any zipped library. Currently 3.4.1, which uses GitHub Releases, is available through CocoaPods, so no problem there.

CocoaPods does support optimistic version referencing and it's generally the preferred practice (specifying '~> 3.2' would mean the highest 3.x.x that's greater than 3.2)

Regarding the ability to remove old versions, which I think is the core issue being addressed here, I'll let one of the more senior contributors to CocoaPods address directly.

I will however give my personal anecdote so you have some insight into why this can be an issue. We use CardIO in our app and we're using CocoaPods to do so. We do update all our libraries every few months, but it seems that in a very short period of time, CardIO released version 3.4 and removed all older versions. This would be fine if CardIO was only distributed as a download, but CocoaPods works slightly differently. It doesn't require you to commit the library to your repo, but instead specifies which libraries should be downloaded for the app to compile (pod install). It specifies a version and locks that version until you upgrade your libraries using pod update. This allows me to know that nothing has changed until I actually sit down to upgrade the libraries and test each one's changes to ensure it still works with our application. It also allows me to know that the other programmers on my team are all using the same version of each library and ensures that our entire codebase is identical.

I hadn't touched this particular project in a month, and I was now working from a new computer, so when I went to set up my environment and ran pod install, it couldn't locate the version 3.3.0 we were referencing, forcing me to upgrade to version 3.4.0 before I could build the project. (And issues compounding from that caused me to lose half a day's work, needlessly.)

In my experience, there are numerous use cases for delaying the upgrade of a library, both engineering and business. There are times when the library has a UI and is tested through automated screenshot comparison. There are times when a crisis has arisen within the end user app and releasing a new bug fix to the app without touching any other code is important. The worst case I've seen for not updating is one where we had a library whose bug fix release broke our app in a serious way, so we locked to a very specific bug release version and weren't able to update past that version for the duration of the development of the app.

So the issue as I see it is thus: CardIO wants to remove old versions immediately upon release of a new version. CocoaPods works more like a pointer reference, so as soon as a version distribution is missing, all users using CardIO must update their CardIO version immediately before doing anything else, unless they have a local cache of the CardIO library already installed.

Is it acceptable for CardIO to offer old versions in a deprecated state?

@alloy, @irrationalfab: please also chime in as you see fit

[josharian]

CocoaPods handles GitHub Releases the way it would any zipped library.

Excellent.

CocoaPods does support optimistic version referencing and it's generally the preferred practice (specifying '~> 3.2' would mean the highest 3.x.x that's greater than 3.2)

Glad to hear it. We're quite careful about following semver, so any way to encourage folks to do this would be preferable from our perspective.

CardIO wants to remove old versions immediately upon release of a new version. [...] Is it acceptable for CardIO to offer old versions in a deprecated state?

To be clear, it's not that we want to remove old versions immediately upon release of a new version. It's that we want to retain the ability to remove old versions.

How would a policy like this sound? We remove old versions when either:

• there is a known, significant security issue with them; we simply cannot distribute versions with known security issues.
• they are > 6 months old; this gives us the ability to eventually deprecate serverside support.

We also commit to notifying the card.io community (via the usual means -- mailing list, twitter, etc.) when old versions are removed, making it clear which versions were removed, and why. (For security-related issues, this may or may not include details of the issues, depending on the circumstances.)

This is actually close to the policy that we have been following, but never made explicit. I'm sorry that we didn't start this conversation ourselves, in happier circumstances.

(To be clear, this would be going forward; we don't intend to repost the now-removed card.io releases.)

[kylefleming]

That sounds great to me. I'll let @alloy or @irrationalfab have the final word on if that works for CocoaPods.

Thanks for understanding!

[josharian]

Great; will wait for a note from @alloy or @irrationalfab before taking any further action on this.

[fabiopelosin]

Although the following opinions might sound a bit too pragmatic I would like to point out, beforehand, that I understand @josharian position.

This would be fine if CardIO was only distributed as a download, but CocoaPods works slightly differently. It doesn't require you to commit the library to your repo, but instead specifies which libraries should be downloaded for the app to compile (pod install). It specifies a version and locks that version until you upgrade your libraries using pod update. This allows me to know that nothing has changed until I actually sit down to upgrade the libraries and test each one's changes to ensure it still works with our application. It also allows me to know that the other programmers on my team are all using the same version of each library and ensures that our entire codebase is identical.

Just to address a minor point, CocoaPods actually allows to add your dependencies to your version control system, and we recommend to do it if you don't trust the reliability source of the library. However not doing so is convenient and as a matter of fact the majority of our users don't do it.

Note that we use semantic versioning

From http://semver.org:

Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

As a package manager developer I consider the above point the ratio for semantic versioning.

What do I do if I accidentally release a backwards incompatible change as a minor version?

As soon as you realize that you've broken the Semantic Versioning spec, fix the problem and release a new minor version that corrects the problem and restores backwards compatibility. Even under this circumstance, it is unacceptable to modify versioned releases. If it's appropriate, document the offending version and inform your users of the problem so that they are aware of the offending version

I hadn't touched this particular project in a month, and I was now working from a new computer, so when I went to set up my environment and ran pod install, it couldn't locate the version 3.3.0 we were referencing, forcing me to upgrade to version 3.4.0 before I could build the project. (And issues compounding from that caused me to lose half a day's work, needlessly.)

According to semantic versioning, which CocoaPods fully adopts, the update should not have required any code change in the client and should not have caused any compounding issue:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.

To be clear, it's not that we want to remove old versions immediately upon release of a new version. It's that we want to retain the ability to remove old versions.
[...]
This is actually close to the policy that we have been following, but never made explicit. I'm sorry that we didn't start this conversation ourselves, in happier circumstances.

I understand why you would like to have this policy set in place. But this is not the optimal solution in my opinion. To properly illustrate my point let me first compare the non CocoaPods and the CocoaPods alternatives.

If your used downloaded the library manually he still would have a copy of the library in his version control system and to update it the user would need to be aware of the update and perform the download again. Removing the library in this scenario provides little benefit for your current users and has the minor advantage of not allowing new users to download an old version of the library (which they are unlikely to do in first place).

In the CocoaPods scenario the user specifies the version requirements and we encourage them to use the optimistic operator, furthermore to check which dependencies have an update they can use the pod outdated command and then they can update their dependencies running pod update (which they are likely to do often as they are pretty convenient and being up to date with the dependencies is one of the main reasons why you might be interesting in using CocoaPods).

CocoaPods, however, to be an acceptable solution has to be reliable. I.e. a core principle is that an installation should not fail, even in future, without user intervention. Nobody likes being forced to deal with an issue while they were interested to address a different one (it just breaks the flow for the programmer). @GARTHEX provided a good anecdote to showcase the issue, but I would like to provide another one. Lets say that I had a project released a year ago and the client asks me to ship an update, the first thing that I would like to do is start from a working state of the release. Discovering that a dependency is not available anymore and that I need to adapt my code for the current release (which given the timeframe might be a major version bump) would not make me happy and likely would lead me to reconsider my practices (ditch CocoaPods, store the dependencies under version control or ditch the dependency).

The reliability principle is also not uncommon in other dependency resolution systems, for example, CocoaPods is inspired to RubyGems which doesn't allow to remove a dependency unless there is a very strong reason to do so and even in this case the only way to do it is to make a request to the maintainers. It is also important to keep in mind that RubyGems has a strong feature that the CocoaPods team decided to not implement – as it would require a non trivial amount of effort that we would prefer to focus on other areas – for the foreseeable future: RubyGems is a package manager as opposed to a library manager. In other words they copy the files of the library and store the package themselves, to guarantee to their users the reliability of the system.

For the above mentioned reason for us is unacceptable to distribute via the master repo libraries whose sources are likely to or might be removed (there are other alternatives as I mentioned in the linked thread).

However I think that your goals are reasonable and I think that there are alternative solutions which might allow to achieve them while adhering to the CocoaPods/SemVer principles. An example might be to make a request to your serves, optionally only for debug builds, which logs a warning (or raises an exception) if the version of the library has been deprecated. I believe that thinking along this axis and exploring other alternative solutions will lead to a more convenient strategy.

[josharian]

I hadn't touched this particular project in a month, and I was now working from a new computer, so when I went to set up my environment and ran pod install, it couldn't locate the version 3.3.0 we were referencing, forcing me to upgrade to version 3.4.0 before I could build the project. (And issues compounding from that caused me to lose half a day's work, needlessly.)

According to semantic versioning, which CocoaPods fully adopts, the update should not have required any code change in the client and should not have caused any compounding issue:

Indeed. And that is a worthwhile discussion to have. @GARTHEX, it would be useful if you would file a new issue to let us know what about the upgrade required work on your part.

However, even if we did fail in our semver obligations in the past (which, if so, is news to us, and something that we take seriously), that is orthogonal to the current conversation about continued availability of old versions.

CocoaPods, however, to be an acceptable solution has to be reliable.

I understand. The question at hand is not whether CocoaPods has to be reliable, but how we can make that compatible with card.io ceasing to distribute old or insecure library versions.

An example might be to make a request to your serves, optionally only for debug builds, which logs a warning (or raises an exception) if the version of the library has been deprecated.

Unfortunately, I think that disabling versions at runtime is no better (and might be worse) than ceasing to distribute those versions.

• If the version still runs (ignoring a log message), then we are really still distributing insecure or deprecated libraries.
• If the version still runs with a bit of effort (catching an exception), then we are effectively breaking our semver promise, and potentially breaking existing integrations in the wild.
• If the version doesn't run at all, it is much worse than if the version had been removed, as we would break existing integrations in the wild.

Do you have other suggestions?

[fabiopelosin]

[...] However, even if we did fail in our semver obligations in the past (which, if so, is news to us, and something that we take seriously), that is orthogonal to the current conversation about continued availability of old versions.

I made this point to showcase that SemVer in practice might not be as simple as it would look form its specification and thus the point that a version can be safely removed if there is a non-breaking upgrade path is somehow mooted.

To clarify, I did not intend to make to make a negative comment about the development of the card.io iOS SDK – which looks like a pretty great service to me – and I think that nor I nor anyone reading this thread is in the position to reach any conclusion from the above point as we are not familiar with the details of the release.

I understand. The question at hand is not whether CocoaPods has to be reliable, but how we can make that compatible with card.io ceasing to distribute old or insecure library versions.

We can't.

The CocoaPods team has invested a significative amount of effort to guarantee the immutability of each released version of a Pod – as we strongly believe on the benefits of this setup – and we would have gone as far as implementing a packaging system if maintaining such a critical service would not require a commitment to monitor it 24h/24h . For this reason I consider pretty unlikely the possibility that we change our mind about this point.

Unfortunately, I think that disabling versions at runtime is no better (and might be worse) than ceasing to distribute those versions.

• If the version still runs (ignoring a log message), then we are really still distributing insecure or deprecated libraries.
• If the version still runs with a bit of effort (catching an exception), then we are effectively breaking our semver promise, and potentially breaking existing integrations in the wild.
• If the version doesn't run at all, it is much worse than if the version had been removed, as we would break existing integrations in the wild.

The exception ideas was, implicitly, intended only for debug builds. The proposal was aimed to increase awareness of deprecations among developers. On the one hand if a developer insist in using a deprecated version usually he would be able to do so removing the versions offers little benefit; on the other hand if a convenient upgrade path is provided I can't see any reason why a developer would prefer to stick with the outdated version and an exception during debug builds would be a pretty effective approach to get them notified.

Regarding other suggestions, I made an example to showcase my point. I don't have any other idea off the bat nor I have the context, of the significant security issues that you have been identifying, necessary to suggest a viable alternative.

[kylefleming]

(The compounding issue was not with the code, but due to the fact that all CardIO tags were either removed or renamed, so none of the versions of CardIO in cocoapods would install.)

[alloy]

Hi @josharian,

First of all, I’d like to make it clear that I appreciate the situation you’re in and this is also a very good discussion for us to have, so we know how to deal with this in the future.

---

Surely I assume you have users that do not use CocoaPods and have vendored your code in their SCM repo? For these users, removing tags from the canonical repo does not do anything. This is usually the way I determine wether or not we need to add support for something in CocoaPods or not.

In this case I think it should be done in a way that benefits all users, regardless of how they pull in the code, especially if this is related to security concerns. Therefore, I think it’s important to take CocoaPods out of the equation here.

So in the end, following roughly what my partner in crime (@irrationalfab) said, it might be best to handle this at the server level, by no longer accepting requests for certain/older client versions, which should automatically make the client trigger an NSError anyways. This can be made nicer to the end-user by using HTTP content negotiation, which would allow for a nice failure message to be used in alerts and whatnot. This would fit in my understanding of SemVer, which is about the library’s API, not the full system per se.

The exception ideas was, implicitly, intended only for debug builds.

I’m not sure it should be limited, a security issue is a security issue. Although @josharian obviously will know better how insecure they deem these versions.

---

Edited to remove the use of ‘surely’, which has been brought to my attention as not being the best choice of words.

[josharian]

@irrationalfab and @alloy, thanks for all the time and effort you've put in talking this through with us; it is greatly appreciated.

I assume you have users that do not use CocoaPods and have vendored your code in their SCM repo?

We do. And the fact that we cannot claw back those versions is a fact of life. (FWIW, I personally think that everything should vendor all their dependencies, but I recognize that that is not a widespread belief.)

it might be best to handle this at the server level, by no longer accepting requests for certain/older client versions

It's a bit more complicated than this, I'm afraid. card.io is designed to work even if an internet connection is unavailable (try putting your phone in airplane mode and using it). And there are multiple kinds of security threats, including malicious users, malicious developers, malicious gateways, etc. We do have a best-effort kill switch in place (similar to what you have suggested), but that only addresses some types of threats. And just to round things out, concocting an appropriate notion of "debug mode" in a static library is not a straightforward task.

As is all too frequently the case, there's no elegant solution available (sigh).

We've had an internal discussion and gone over the alternatives here, and unfortunately, I think that keeping the ability to remove old versions is an important tool we're not ready to give up.

Much as we dislike the conclusion, given the situation, card.io might just not be a good match for CocoaPods. (Or maybe the pods just need to come with a highly visible warning message?)

Thanks again for the thoughtful discussion.

[josharian]

Oh, and as an aside (but perhaps an interesting one):

This would fit in my understanding of SemVer, which is about the library’s API, not the full system per se.

True, although in light of #25, in which the library API did not change and yet we broke someone's build anyway, we're starting to think that the spirit (if not the letter) of semver requires that we think about the full system.

[josharian]

Thanks for the info, @GARTHEX.