search

tvdstaaij / node-git-describe

Git describe information at runtime, with semver support
36 stars 5 forks source link

distance must be included in the prerelease part of the semver string #7

Closed geogeim closed 6 years ago

geogeim commented 6 years ago

From the spec item 3:

Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

So if we have commits on top of the tag, we must consider it as a different version.

From the spec item 9:

Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.

I think it's safe to assume that we can consider these commits as part of pre-release string. Also, i think the distance should be added to the pre-release only if it is non-zero.

tvdstaaij commented 6 years ago

You are right that a repository state with changes on top of a valid semver tag is not equivalent to the release denoted by that semver. However, as I see it, a repository state does not necessarily constitute a valid release at all. Any commits on top of a release are simply development versions until a commit is tagged as the next (pre)release. In fact, commits after a release could never be a pre-release version of that release by definition, since pre-releases always come before the release itself. This can be inferred from the term "pre-release" but is also explicitly mentioned in the part of the spec you quote ("Pre-release versions have a lower precedence than the associated normal version." -- meaning they come before the normal version in an ordered list, see item 11).

That being said, since all components of the generated string are also provided separately, it is entirely possible to format a string according to custom needs and preferences. Or simply detect whether the current repository state is a valid release (e.g. has a valid semver tag, zero commit distance and possibly a non-dirty state).