Project

General

Profile

Actions

Task #2004

closed

Ensure software version string conforms to Semantic Versioning

Added by Junxiao Shi over 9 years ago. Updated about 9 years ago.

Status:
Rejected
Priority:
Normal
Category:
Build
Target version:
Start date:
Due date:
% Done:

10%

Estimated time:
2.00 h

Description

Ensure software version returned by nfd --version and similar commands conforms to Semantic Versioning 2.0.0 spec.

This includes not only release versions, but also pre-release versions.
Transformation from git --describe output may be necessary.


Related issues 1 (0 open1 closed)

Related to NFD - Task #2003: StatusServer: include NFD version in NfdVersion fieldClosedHila Ben Abraham

Actions
Actions #1

Updated by Junxiao Shi over 9 years ago

  • Related to Task #2003: StatusServer: include NFD version in NfdVersion field added
Actions #2

Updated by Felix Rabe over 9 years ago

Related: https://github.com/named-data/ndn-js/pull/43/files

When I was writing that file CONTRIBUTING.md, I was also thinking about mentioning semver.org, but then I left it out, so NDN can either follow it globally, or not follow it, and the instructions work independently either way.

Also, I think it would be worthwhile to discuss naming conventions for platform 0.4. I'd opt for all-lowercase and dash-concatenated names, as this convention to be common for software packages. (This might be worth a separate issue.)

Actions #3

Updated by Felix Rabe over 9 years ago

Clarification: I'm advocating package names such as chrono-sync, nfd, nlsr, and maybe even ndn-py (instead of PyNDN), ndn-java (instead of jndn). This would make documentation (http://named-data.net/codebase/platform/) and GitHub (https://github.com/named-data/) look more regular, and keep future devs from thinking about "is this package upper- or lower-case? camelCase? ..."

Actions #4

Updated by Felix Rabe over 9 years ago

Yet another issue (sorry for highjacking this, I'm just super-tired - bug me via email if I don't clean this mess up in the next few days):

I propose we should create a separate repository on GitHub (e.g. named-data-attic or -archive or -contrib or -misc) and move most packages from https://github.com/named-data/ there, so that only the actively-developed remain.

GitHub automatically keeps old names available via a redirect, so this will not break links.

Actions #5

Updated by Junxiao Shi over 9 years ago

note-2 and note-3 are irrelevant to this issue.

Software version string does not contain project name. It may look like "0.2.0".

Actions #6

Updated by Davide Pesavento over 9 years ago

Unless it's urgent, I plan to do this right after Christmas (but before the 29th).

Actions #7

Updated by Davide Pesavento about 9 years ago

  • Status changed from New to In Progress
  • % Done changed from 0 to 10
Actions #8

Updated by Davide Pesavento about 9 years ago

What's the expected output for shallow clones? Tags are not available in that case. An example output could be 0+<commit-SHA> or 0.0.0+<commit-SHA>. (It's kind of a corner case so I wouldn't worry too much anyway)

Also, do we want to change the hyphen to a plus sign or not? (e.g. NFD-0.2.0-42-gdeadbee => NFD-0.2.0+42.gdeadbee)

Actions #9

Updated by Davide Pesavento about 9 years ago

  • Status changed from In Progress to Feedback
Actions #10

Updated by Junxiao Shi about 9 years ago

I have no opinion on both questions in note-8. As long as the output conforms to the semver spec, it's fine.

Actions #11

Updated by Alex Afanasyev about 9 years ago

Davide Pesavento wrote:

What's the expected output for shallow clones? Tags are not available in that case. An example output could be 0+<commit-SHA> or 0.0.0+<commit-SHA>. (It's kind of a corner case so I wouldn't worry too much anyway)

For shallow copies we already have the following version format:

<base-version>-commit-<commit-SHA>

For example:
0.2.0-commit-a22a217

Just change it to

<base-version>+commit-<commit-SHA>
0.2.0+commit-a22a217

Also, do we want to change the hyphen to a plus sign or not? (e.g. NFD-0.2.0-42-gdeadbee => NFD-0.2.0+42.gdeadbee)

I agree with this. According to the semantic versioning spec, the git commit number is build meta information and should be separated with +. I also checked that it doesn't violate anything with ubuntu package versioning.

Actions #12

Updated by Davide Pesavento about 9 years ago

Alex Afanasyev wrote:

For shallow copies we already have the following version format:

<base-version>-commit-<commit-SHA>

For example:
0.2.0-commit-a22a217

The problem is that currently the base-version is hardcoded in wscript. I wanted to get rid of that, since it's kinda redundant and must be manually incremented at each (pre-)release.

I agree with this. According to the semantic versioning spec, the git commit number is build meta information and should be separated with +. I also checked that it doesn't violate anything with ubuntu package versioning.

That's debatable... what does "build metadata" mean? IMO it should be used to encode different ways of building the same code (i.e. same commit SHA). Under this interpretation the number of commits or the git SHA are not build metadata.

In any case, what's the advantage of using the + syntax? Semver sucks with respect to version ordering (except for trivial cases), and the ordering rules for + are totally useless:

Build metadata SHOULD be ignored when determining version precedence.

Actions #13

Updated by Alex Afanasyev about 9 years ago

Davide Pesavento wrote:

Alex Afanasyev wrote:

For shallow copies we already have the following version format:

<base-version>-commit-<commit-SHA>

For example:
0.2.0-commit-a22a217

The problem is that currently the base-version is hardcoded in wscript. I wanted to get rid of that, since it's kinda redundant and must be manually incremented at each (pre-)release.

This operation is kind of rare and I wouldn't worry about that. I would also change hard-coded version only for actual releases.

I agree with this. According to the semantic versioning spec, the git commit number is build meta information and should be separated with +. I also checked that it doesn't violate anything with ubuntu package versioning.

That's debatable... what does "build metadata" mean? IMO it should be used to encode different ways of building the same code (i.e. same commit SHA). Under this interpretation the number of commits or the git SHA are not build metadata.

Hmm. I didn't find the spec defined "build metadata" anywhere. The point I got was that, according to spec, anything after + shouldn't get involved into version comparison. This is exactly what the intention for commit hash---hashes are not comparable and the number of commits that sometimes is put in front is not always precise science.

In any case. My position is that if there are no major problems with current way, I prefer keeping things as is. If there is good argument for the change, I'm ok with the change.

In any case, what's the advantage of using the + syntax? Semver sucks with respect to version ordering (except for trivial cases), and the ordering rules for + are totally useless:

Build metadata SHOULD be ignored when determining version precedence.

I don't really care. If you want to keep the current way, I'm fine too. Ubuntu uses ~ separator with special ordering rules, but I don't think it applies here (and it is not part of version spec).

Actions #14

Updated by Davide Pesavento about 9 years ago

Junxiao asked for an update on this task. I haven't made further progress since there is no consensus on how to proceed. I'm not sure if we should really adopt semver, it doesn't give us any clear benefit. Alex seems to be fine with the status quo too.

Actions #15

Updated by Junxiao Shi about 9 years ago

semvar was adopted when I initially give NFD a version number. The benefit of semvar is to ensure backward-incompatible change bumps MAJOR version (except 0.x.y) so that it's more visible.

Please indicate what problem is blocking further progress on this issue.
This issue is simply doing a transformation so that the string doesn't contain any character that is disallowed in semvar.

Actions #16

Updated by Alex Afanasyev about 9 years ago

Junxiao. What exactly you want to be done as part of this task? I see nothing that needs to be done here.

We already use versioning system that conforms to semantic versioning. Version that is returned by nfd --version in most cases (excluding building from a shallow clone) is the version that includes all necessary information we want to include and is numerically comparable (if the build is from master branch).

Actions #17

Updated by Junxiao Shi about 9 years ago

I created this issue because @Davide said the version number can contain a certain character that is illegal in semvar. Is it still the case?

Actions #18

Updated by Davide Pesavento about 9 years ago

That's not what I said. If you're referring to #1916 note-19, we were talking about the output of git describe, which is not used directly as the NFD version (and btw the prefix we use for release tags is "NFD-", not "v").

Actions #19

Updated by Junxiao Shi about 9 years ago

  • Status changed from Feedback to Rejected

This Task is unnecessary because version string is already conforming to semver spec.

Actions

Also available in: Atom PDF