Support for v-prefixed version tags in SPM / Swift Playgrounds for iPad


I was reported that feedback FB9833870 (SemVer issues with package dependencies in SPM) was resolved as "Investigation complete - Works as currently designed". I regret that this resolution was chosen, and I look for support from the SPM team and other community members so that it is reconsidered.

The initial problem is that Swift Playgrounds for iPad does not recognize semantic version tags prefixed with "v". It displays an error message, telling that the "package does not have version tags" (screenshot).

This is an incorrect and misleading error message. Tagging git commits with "v..." tags is a valid way to express semantic versions. Quoting

[...] prefixing a semantic version with a “v” is a common way (in English) to indicate it is a version number. [...] Example: git tag v1.2.3 -m "Release version 1.2.3" , in which case “v1.2.3” is a tag name and the semantic version is “1.2.3”.

This incorrect behavior is specific to Swift Playgrounds for iPad. SPM in the command line, SPM embedded in Xcode, and other package managers such as CocoaPods deal nicely with "v..." tags.

Many repositories in the wild use "v..." tags. Some of them are quite popular. Their tagging scheme predates the existence of SPM and Swift Playgrounds for iPad by several years. For example: Realm, KeychainAccess, AudioKit, GRDB, ...

This incorrect behavior has users of those libraries report issues (1, 2, 3, 4, more).

Library maintainers do not want to retag their libraries, since this could break the workflow of existing users who rely on specific tags/commits. The job of library maintainers is indeed to protect their users and avoid breaking changes that can be prevented. Support from tooling would be appreciated.

An option for library maintainers would be to dual tag their libraries (tag a commit with both v1.2.3 and 1.2.3). But those would create new problems. SPM is known for not supporting this (evidence). Dual tagging creates the opportunity for conflicting tags (if v1.2.3 and 1.2.3 do not tag the same commit). Dual tagging creates difficulties for programs which process tags. And finally, forcing library maintainers to change their tag policy would be a surprising signal in the calm sea of tagging schemes.

All in all, I wrote this report and arguments because I hope that FB9833870 and other similar feedbacks are reconsidered. Thanks for reading!


For the record, and as a support for those claims, here are two places in the SPM repository that show the support for "v"-prefixed tags that is lacking from Swift Playgrounds for iPad:


I second this. While “v1.2.3” isn’t a semantic version, it is explicitly noted in the standard as a common way to express a semantic version of “1.2.3” in a Git tag (that is, in this exact scenario).

SPM support for “v” prefixes should also be explicitly documented and required, to prevent this sort of mismatch from recurring in future implementations.

Alternatively, prefixes like this could be explicitly not supported, and all future versions of SPM could be required to reject them. That would obviously cause issues, but it is still preferable to inconsistent support. There must be no ambiguity about what constitutes an SPM version tag.


I think somewhere in the GH issue discussion two issues became conflated, the feedback you're linking was asking for this syntax to work in Xcode:

.package(url: "", from: "v5.17.0")

which, as far as I know, it never did, in either SwiftPM or Xcode. This is why it was marked as "behaves correctly".

The Swift Playgrounds issue you are mentioning seems only related in so far it is also about v prefixes and I tend to agree with your argument here that this should behave like Xcode and SwiftPM do.

Thank you @NeoNacho. The original feedback (which I could not read), was indeed not well written, I can now see it. I share your diagnostic about it. I'm happy that the issue with v-prefixed tags is identified as such. Have a nice day!

1 Like

I still think the expected tag format (a semantic version, optionally prefixed with v) should be spelled out explicitly in the SPM documentation.

We should specify SemVer 2.0 while we’re at it. It’s a bit ironic that people rarely do.

1 Like