Feature request : Generating PEP440 compliant versions

[franknarf8]

Hello,

We are using GitVersion to version packages written in many different languages and up to now; most package managers are supporting classic SemVer.

We now want to use GitVersion to version for our Python packages; thing is, the Python community decided to invent their own version standard which is not compatible with SemVer : PEP440.

e.g. a pre-release tag can only be equal to a predefined list (So something like 0.6.3-featurebranch.10 is forbidden) (See https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions)

I know GitVersion is mainly .Net oriented, but would it be possible to also print out PEP440 compliant version numbers along with the other versions numbers? And while leveraging the various development mode GitVersion offers?

Thanks again, we love your tool!

- Frank

[asbjornu]

I see no problem adding support for PEP440, but before we write any new code in GitVersion, it would be good if you could try the various configuration options GitVersion provides to see whether it gives you the desired result.

If you add tag: <custom-label> to your GitVersion.yml for every branch that is being built, are you able to achieve what you want?

[franknarf8]

Hello @asbjornu ,

Thanks for the tip! I've just tried playing around with the possible GitVersion.yml configurations; and the following branch description seem to fit the parsing regex from PEP440.

branches:
  master: {}
  release:
    tag: 'rc'
  feature:
    tag: 'dev'
  develop:
    tag: 'a'
  hotfix:
    tag: 'post'

Such configurations are generating versions which look like : 0.6.3-dev12 and 0.8.0-a.12.
The PEP440 parser is able to read those version numbers, but will translate them to fit the Public Version Identifier defined by the standard ([N!]N(.N)*[{a|b|rc}N][.postN][.devN]) : 0.6.3.dev12 and 0.8.0a12 respectively.

I still think it would be quite nice to integrate this standard directly into GitVersion, as it would be nice to generate a version number following the Public Version Identifier format directly, and also to avoid setting those configs in every single python project.

What do you think?

[asbjornu]

Thanks for figuring out the required config to get this to work. It's very helpful to see for someone not intimately familiar with PEP440 such as myself. If we were to introduce a variable that changed the default pre-release tags for all branches to be PEP440 compliant, how would you suggest that will look like?

[franknarf8]

Well, that is exactly the problem I encountered that pushed me to open an issue here.
The different pre-release tags are limited to the following (a|b|c|rc|alpha|beta|pre|preview). (As per the regex defined in PEP440...)

[asbjornu]

Yes. I don't want to change the GitVersion defaults to be PEP440 compatible, since its's PEP440 that is the odd one out here not supporting SemVer 2.0. But we can add a configuration option to GitVersion.yml that would switch to PEP440 compatible pre-release labels. What would you suggest such a configuration should look like? Are there more pre-release label schemes similar to PEP440 we ought to support, now or in the future?

[franknarf8]

Yeah, neither do I; the gitversion standards/defaults are sane.

Adding some kind a switch to tell gitversion we want to print out PEP440 compliant versions sound like a good idea.

Maybe we could add something like the following option to the GitVersion.yml file :

pre-release-labels-type: PEP440 # defaults to SemVer2

(or pre-release-labels-format, or any better naming)

And then, if that switch is enabled, gitversion could print out something of the sort :

{
  "Major":1,
  "Minor":2,
  "Patch":3,
  "MajorMinorPatch":"{Major}.{Minor}.{Patch}",
  // Not sure of the difference between 'CommitsSinceVersionSource' and 'PreReleaseNumber'
  "CommitsSinceVersionSource":4, "PreReleaseNumber":4,
  "BranchName":"X",    // master, develop, release/1.2.3, feature/branch, hotfix/1.2.3
  "PreReleaseTag":"Y", // "",     "a4",    "rc4",         ".dev4",        ".post4"
  // Not sure of the difference between 'SemVer' and 'FullSemVer'
  "SemVer":"{MajorMinorPatch}{PreReleaseTag}", "FullSemVer":"{MajorMinorPatch}{PreReleaseTag}", 
  "Sha":"whatever",
  "ShortSha":"whatev",
  "CommitDate":"2020-03-11"
}

Where the X:Y matching could look like this :

"master" -> ""
"develop" -> "a4"
"release/1.2.3" -> "rc4"
"feature/branch" -> ".dev4"
"hotfix/1.2.3" -> ".post4"

I am not aware of other version schemes (but woundn't be surprised if I stumble across one tomorrow); SemVer is pretty much established as a strong standard, the python community just likes to reinvent things.

What do you think?

[asbjornu]

I think the word scheme is more consistent with the existing configuration, so pre-release-tag-scheme would be a good name of such a configuration property, with the values SemVer2 (default) and PEP440. 👍

I like the word label better than tag, but #1054 is tracking the rename from tag to label, so we have to do that in one big sweeping change for a new major version of GitVersion.

[arturcic]

@asbjornu just add the milestone 6.0.0 so that we can track it

[asbjornu]

I just realized that the de facto standard package manager for PHP, Composer, implements a subset of SemVer in its requirement of prerelease labels of version to be one of the following values:

• -dev
• -patch (-p)
• -alpha (-a)
• -beta (-b)
• -RC

Otherwise, I believe Composer's implementation is SemVer 2.0 compliant. It's therefore not unthinkable that pre-release-tag-scheme can be expanded with more values in the future. A pull request implementing this would be welcome, @franknarf8.

[asbjornu]

Seems like also Ruby Gems have a strict interpretation of what makes a valid prerelease label.

[asbjornu]

Docker is another one with peculiar format requirements for its tags. I've discovered that + yields the "invalid reference format" error, but I'm sure there are other characters that aren't allowed in there as well.

[pniederlag]

Docker is another one with peculiar format requirements for its tags. I've discovered that + yields the "invalid reference format" error, but I'm sure there are other characters that aren't allowed in there as well.

that's quite true. docker tags are not full semVer compitble. However, imho this only affects the build metada (indicated by +).

this ticket seems to be about PEP440 compliancy, or in a broader scope, the generation of the PreRelease* Properties. Maybe it's wise to keep the metadata issue on docker tags out of here for now...

@asbjornu thx for guiding me here (coming from #2353), solving PEP440 problems seems to be quite similar to my problem.

@franknarf8 could you pls add two example on what PreRelease* and SemVer* Properties you would like to see, so I can check wether we are really in the same boat?

In general I'd always think some formatting-string with attached variables (like I can use {branchName} on branches.XX.tag="dev-{BranchName}" has great flexibility, if {PreReleaseNumber} was available (and baked in by default), anyone trying to get rid of it could just get that done.

Do I understand correctly that {PreReleaseNumber} is just the commit-count since the last release? Effectivly this is the commit-count since the last tag?