How to version this crate

[rotty]

This is intended as a discussion issue, aimed at resolving these two questions:

• How should this crate be versioned? Ideally the versioning scheme should allow mapping the crate version to the corresponding libzmq release. Probably adopting, maybe with adaptions, the scheme that the openssl crate uses is a good idea.
• How would that versioning map to git branches? I see that currently the master branch tracks libzmq's master. I guess that's fine, but I'm not sure if it's a good idea to publish unreleased snapshots of the libzmq source code to crates.io.

[jean-airoldie]

Yes. The master branch is quite experimental and might make breaking changes at any time. I think at the very least two parallel versions should be exist: the master branch and the latest release branch.

The master branch does not necessarily need to be published on crates.io in my opinion. So we could maybe exclusively publish that latest release.

I'll look into what openssl is doing.

[jean-airoldie]

The openssl-src crate, from my understanding, is using the following versioning from the semver spec:

Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

Following that logic, the current version should be 0.1.2+4.3.1.

There is a potential issue however since it is stated that:

Build metadata SHOULD be ignored when determining version precedence

This means that using this versioning a newer libzmq release would not take precedence over a older one.

[jean-airoldie]

I found this issue in cargo relating to this.

To sum it up, right now the build metadata is ignored (which is in accordance to the specs). This means that lets say we publish 0.1.2+4.3.1 followed by 0.1.2+4.3.2, 0.1.2+4.3.1 will have to get yanked as it is semantically equivalent.

[jean-airoldie]

We could consider the libzmq gitsubmodule as part of the crate when versioning. This way someone could depend on a specific libzmq version if he wants.

Here is a an example:

# the libzmq dep's minor version was bumped
`0.1.2+4.3.1` => `0.1.3+4.4.0`
# a minor change was made in the crate's logic
`0.1.2+4.3.1` => `0.1.3+4.3.1`

But this seems kinda tricky and potentially error prone.

[jean-airoldie]

We could also only change the crate's build metadata but that would force new users to use the lastest stable release (since the previous is yanked). Moreover, if the libzmq introduces a breaking change, it won't be accounted for in the crate's versioning.

Here is an example:

# The previous version is yanked, only the new one remains.
`0.1.2+4.3.1` => `0.1.2+4.4.0`
# This is a breaking changed, yet we do not acknowledge it.
# Users are forced to use the newest lib.
`0.1.2+4.3.1` => `0.1.2+5.0.0`

[jean-airoldie]

We could also directly map to libzmq's version but that would not allow use to introduce any API changes exclusive to the crate. Since we likely want this crate to potentially build on currently unsupported platforms (such as windows), this is not realistic.

[jean-airoldie]

I think the first versioning scheme, should work pretty well.

[jean-airoldie]

I added versioning information to the readme to make that clear.