Tag release versions

[betamike]

I recently added CocoaLumberjack to the CocoaPods package manager.

Since CocoaLumberjack doesn't currently have a discreet version, I treated the current commit as the 1.0 release. Would it be possible to have this commit tagged as v1.0 (or whatever version you feel comfortable with)? This will help greatly in dependency resolution.

Thanks!

[robbiehanson]

You pose an interesting question: Why not tag release versions?

I've got a couple open source libraries. Some of them are pretty big projects (like XMPPFramework). With the big projects I do typically tag major releases. But with the smaller libraries (like CocoaAsyncSocket, CocoaLumberjack) each commit is stable, and presents a small improvement upon the previous revision. In cases like this, I usually avoid using tags...

But adding tags can't hurt, right?

Well, yes and no. And here's where I'd really like to get your expert feedback.

In the past I did always use tags. But as each commit was a minor improvement, there weren't many times when I felt the need to go tag a new major release. Over time, the notion of tags was nearly forgotten. But every so often I have a discussion with someone that went something like this:

Dev: "I'm seeing this bug that does ..."
Me: "That sounds like a bug I fixed a long time ago. What revision are you on?"
Dev: "Version 1.X"
Me: "What? That's from forever ago. Why aren't you using a more recent version?"
Dev: "I thought this was the most current stable release..."

So my fear is that if tags are present, users will get the notion that they should only use the most recent tag. And only update when I tag a new version. But with the smaller libraries, I'd prefer users grab the latest master, and update when possible (or just about whenever I push a new batch of commits).

Thoughts?

[betamike]

Hmm, yes, I definitely understand where you're coming from. Ideally, how would that be handled for something like a library manager? Would you want the package to always check out the lastest master?

It gets hairy at the point where my Library A depends on your Library B. What happens if you make a major change to a method signature (or something of that nature)? I wouldn't be able to say that Library A depends on v1.0.3 of Library B. Then again, perhaps we could use the commit hash as an identifier?

@alloy how do you feel about that?

[alloy]

Yeah, unfortunately, I know the issue of devs not interpreting version numbers well or assigning emotional value to certain version numbers.

However, arbitrary revisions as version is not a good idea for a library manager vs a proper version number (see Semantic Versioning). Let me explain how, in an ideal world ;), I’d prefer people to interact with it:

• “I want to start using CocoaLumberjack, the current version will be fine for now.” So the dev adds a dependency on the lib without a version requirement and lets the manager install it which will use the latest version:

  spec.dependency 'CocoaLumberjack'
  

• Some time into the future, the dev wants to update the dependencies so runs the install command again, which will now install the version of the lib which is the latest version at that time.

• At some point the dev is finished on the client work (or a newer version of the lib changes the API and the changes aren’t needed) so the dev adds a version requirement to the dependency. For instance, consider that the author of the lib follows the server guidelines, you can somewhat trust that between ‘1.0.7’ and ‘1.1.0’ no API changes will be made, but only bug fixes. So instead of requiring a specific version, the dev can specify that any ‘1.0.x’ is allowed as long as it’s higher than ‘1.0.7’:

  spec.dependency 'CocoaLumberjack', '~> 1.0.7'
  

The point is that devs can easily keep track of newer versions of dependencies, by simply running pod install again, which they might otherwise do less if they had to change everything manually.

Now I understand that wether or not you want to do this is totally up to you, we can tag any revision as a version, but it would be much clearer to everyone if the version can be traced back to a tag in the actual repo.

I hope this makes any sense, I’m a bit wasted atm, I’ll double-check in the morning :)

[robbiehanson]

So instead of requiring a specific version, the dev can specify that any ‘1.0.x’ is allowed as long as
it’s higher than ‘1.0.7’

I really like this idea. Question:

What if the latest tag is '1.0.7' and there have been several commits since then? Since no commits have been tagged as 1.1.X, would it pull these iterations? Or does it not pull since there aren't any new tags?

And if a 1.1 tag was added, would it pull the latest commit prior to that tag?

[alloy]

What if the latest tag is '1.0.7' and there have been several commits since then? Since no commits have been tagged as 1.1.X, would it pull these iterations? Or does it not pull since there aren't any new tags?

And if a 1.1 tag was added, would it pull the latest commit prior to that tag?

It won’t pull any newer commits, just exactly what’s specified in the pod spec. It’s not possible to know if the dev of the lib is making API changes on branch X, so assuming newer commits will be ok is going to hurt kittens ;)

Note, though, that it is very likely that in the future it will be possible to optionally use the ToT of a lib, it just hasn’t been implemented yet. This is also because it would only work if the author of the lib keeps a copy of the pod spec in the repo that’s up-to-date for the required source files at that point in time. This is something I’d like lib authors to start doing anyways, but before I start asking that I want to make sure the basics work well and supply a few tools to make it easy for lib authors to generate/push newer specs.

[alloy]

PS: Since Mike has added your lib to the specs I have started using it. I like it. Thanks! :)

[robbiehanson]

It’s not possible to know if the dev of the lib is making API changes on branch X,
so assuming newer commits will be ok is going to hurt kittens ;)

First : that's hilarious.

Second : good point.

So when I do make an API change, I'll be sure to:

1. tag a new version (e.g. tag=1.1)
2. tag the prior commit (e.g. tag=1.0.4)

And if I don't make any API changes, but have several revisions since the last one, then it's probably just good practice to eventually tag another commit. (in other words, I'll stop being so lazy)

P.S. - I've added tags.

[alloy]

Yeah, that sounds about right :)

Awesome, thanks a lot!