Semver

[joshbeitler]

It would be nice to have a shield for Semver that could represent version numbers in a project.

[reiz]

@joshbeitler How should that look exactly? Just a batch with a version number? Or something else?

[joshbeitler]

Sort of like this: . Something like this was suggested here on the Semver issue page.

[reiz]

Yeah. That looks good. Maybe it would encourage the java folks to use semver! :-D

[joshbeitler]

Ha!

[Jamesking56]

👍

[olivierlacan]

Allow me to be the usability nutcracker here, but that sv makes it very difficult to parse (with your eyes) the version number attached to it.

In keeping with the idea of making open source projects approachable I would rather spell things out than use initials or even abbreviations:

semantic version | 0.2.5
version | 0.2.5

Plain and simple, no frills. If you're semantic, it's explicit and you can boast it. If you're not, we don't mention it.

What do you folks think?

[thedrow]

@olivierlacan I agree! +1

[joshbeitler]

That seems like a much better idea than my initial suggestion 👍

[Jamesking56]

I really love this idea and would love to express that I'm a part of Semantic Versioning more in my projects 👍

How would you catch every single possible version number as well as prerelease version number though? Or can the version number part be generated by how you link it?

[ackerdev]

@Jamesking56 it would probably be dynamic, yes.

[Jamesking56]

But wouldn't that mean that every new version you would have to update Readme.md with the new version number? The other status badges for services update themselves but this one seems to require manual updating?

On 9 Aug 2013, at 05:00 PM, Nicholas Acker notifications@github.com wrote:

@Jamesking56 it would probably be dynamic, yes.

—
Reply to this email directly or view it on GitHub.

[chadwhitacre]

I like @olivierlacan's idea that we use two badges related to versioning: one would be for the version number of the package in question, and the other for the version of SemVer in use. So it'd look like this:


Or maybe even:

The package version could be resolved dynamically using the relevant package repo (packagist, npm, rubygems, pypi, cpan, etc.) as the backing service. Since the version of SemVer you're using wouldn't change that often, it's less onerous for that to be static in your markdown. The above would look something like this:

[![](http://shields.io/packagist/myproj.png)](link) [![](http://shields.io/semver/v2.0.0.png)](link)

We could then dynamically color-code the SemVer badges based on the age of the version of the SemVer spec in use. Maybe green for the latest version of SemVer, yellow for pre-releases of the latest version, and red for old versions?

[chadwhitacre]

It would be easy to add a SemVer service once we land #44.

[Jamesking56]

Yeah, once this is a service maybe then we can just login to some backend to update the version number or maybe it might be easier to use GitHub's API to get the Releases on a repo and use the version number on that?

[thedrow]

Or read it from setup.py/AssemblyInfo.cs etc. and try to parse it as SemVer.

[jmalloc]

For what it's worth, I was the one who created the original badge task on the SemVer repo. My preference is to construct READMEs such that the badge shows the version of my project, and links to the spec for the SemVer version in use. That way you're not bombarding the user with too much information, but there's no ambiguity as to the scheme in use. I haven't found updating the README for each release to be problematic as I just do it at the same time as the CHANGELOG.

example:

[chadwhitacre]

On semver/semver#104 (comment), @Tieske suggests:

using the sv postfix, it could simply be appended; 1.2.3 sv2.0.0 package version 1.2.3 based on SemVer 2.0.0.

Here's what that might look like:


[olivierlacan]

@whit537 How legible is that for someone who doesn't know what sv means or why there are two version numbers being displayed?

This doesn't satisfy the "semantic" goal of Shields at the moment.

I still favor one badge that says:

version | 1.2.0

and another one that says:

semantic version | 1.2.3

Trying to cram too much information in one badge doesn't look like a good solution.

[ackerdev]

Backing @olivierlacan on this one.

[Jamesking56]

I agree with @olivierlacan actually.

[chadwhitacre]

@olivierlacan Would the version | 1.2.0 badge link anywhere?

[Jamesking56]

@whit537 Maybe it should be version | 1.2.0 and link to the relevant SemVer spec (e.g. http://semver.org/spec/v2.0.0.html)

[ackerdev]

@Jamesking56 I could see that working.

[chadwhitacre]

Or we link version | 1.2.0 to the specific version in the relevant package manager. I mean, really, the user is in control of where they link to, as they are the ones editing the markdown (etc.).

[ackerdev]

That's possible, though I would think it would be better all around for that package manager to integrate with Shields in the first place 😄

[chadwhitacre]

@ackerdev Sure, but the user is still going to copy and paste markdown, right?

[ackerdev]

@whit537 Yeah, and they of course can still edit it to do whatever they want... but I would think if this is for SemVer then the badge should point to SemVer by default.

[chadwhitacre]

@ackerdev The SemVer badge certainly should. I was wondering about the version badge.


[![](http://shields.io/semantic version/v2.0.0.png?color=green)](http://semver.org/spec/v2.0.0.html) [![](http://shields.io/version/1.2.0.png?color=green)](http://www.example.com/)

[thedrow]

@whit537 What you suggested is the best solution. Two badges will clear out any issue.
You can also do something like:
version | 1.2.0
= = = = = = = = = = = = =
semantic | version v2.0.0.

Also what if the version does not conform semantic versioning and semantic versioning is specified. Should the version badge turn to red?

[Tieske]

When I suggested

using the sv postfix, it could simply be appended; 1.2.3 sv2.0.0 package version 1.2.3 based on SemVer 2.0.0.

I meant the ability to add it to the SemVer version itself, the SemVer string for a package.
I think that communicating a version and the actual details of the version are two separate things. Similar to not including the build metadata when marketing a new version, you also wouldn't include the SemVer version.

So if the version would be (with the proposed extension) 1.2.3 sv2.0.0, then that would be machine parsable for package managers and the like (currently SemVer lacks a way to determine the version of SemVer to compare against). But when communicating the version with a user, it should simply state 1.2.3. As most users wouldn't care about SemVer. The SemVer version could be documented somewhere in the readme, or it could be displayed in an 'about' dialog that it should be compared as SemVer 2.0.0.

So as for the badge; I think it should display the version of the package, and the (visual) design should make clear that it uses SemVer (link to the apropriate SemVer version maybe, as @Jamesking56 commented). But I don't see the need to make it display the SemVer version used in the badge.

For the future it would probably be best if SemVer would define a logo or some design guidelines for displaying versions so it gets a consistent implementation over all uses (similar to the facebook 'like' logo)

[ackerdev]

@whit537 I actually didn't think about it, but semantic version | 2.0.0 would seem to be a useless badge. version | 1.3.7 should just link to SemVer, since we'd be considering this a manually updated badge that indicates the version of this repository/package, it would seem strange to have a badge to denote the version of the semantic versioning being used, when the version badge could link to that version of the semver doc.

Though we do lose some use in declaring it to be semantic versioning this way to the reader. Could just be semantic version | 1.3.7 where 1.3.7 refers to the version of the repository/package, and still links to the SemVer 2.0.0 doc, though I think that could be confusing.

[olivierlacan]

For the future it would probably be best if SemVer would define a logo or some design guidelines for displaying versions so it gets a consistent implementation over all uses (similar to the facebook 'like' logo)

That's a really good idea @Tieske. I created an issue on the semver to suggest that.

I think the solution here is simple:

version | 1.3.7 semver | 2.0.0

The version badge links to whatever package manager or archive of the version release, while the semver badge links to a specific semver spec version: http://semver.org/spec/v2.0.0.html