[RFC] Versioning scheme for commit-based versioning

[korewaChino]

Right now, the unwritten rule for commit/snapshot-based RPM package is to version it using this format:

%{date}.%{shortcommit}

This is not documented very well, and we may get inconsistent versioning from various contributors for nightly or any packages without a proper release.

I propose a universal, consistent versioning scheme for Terra packages that do not have a concrete release tag upstream or builds from a specific commit.

The format is as follows:

• The date of the commit (In a YYYYMMDD Format)

• The VCS used (i.e Git), should be shortened to 3 characters, at most 4. For example:

  VCS	VCS ID (for Terra)
  Git	git
  SVN	svn
  CVS	cvs
  Bazaar	bzr
  Mercurial	hg
  Perforce (Helix)	p4
  Pijul	pjl
  Azure DevOps	tfs
  darcs	darc
  Fossil	fsl

• The snapshot/commit ID of said VCS that it built from, with a tilde (~) separating the VCS and commit ID to work around RPM restrictions (7 Characters for Git SHA256 hashes and other short-form IDs for other VCSes)

So for example, a Git-based package would be named this:

%{date}.git~%{shortcommit}

20240815.git~abcedfg

We should also document a workflow for at least Git, to use macros when doing Git commits, or write our own macro to shorten SHA hashes.

%global shortcommit %(c=%{commit}; echo ${c:0:7})

[linear[bot]]

FYRA-65 [RFC] Versioning scheme for commit-based versioning

[sadlerm4]

Tildes serve a specific purpose in RPM versioning, so I would be more inclined to use a hyphen instead if the VCS identifier needs to be separated from commit ID (not sure what the RPM restriction that you mentioned is), i.e.20240815.git-abcdefg

I agree that the common <date><scm><version> is a mess without any visual separation, and the simple <date>.<revision> is inadequate when not prepended with ^ or ~ when used for packages that have never had a proper release.

If we were being consistent with upstream Fedora here, all of these packages should really have a major version of 0, as in 0^20240815.abcdefg - see nvidia-patch package

That being said, I like that you're trying to do something better here. Another option is to incorporate the + sign, since it doesn't do anything in RPM.

[korewaChino]

tildes are reserved for specifying the release only, so you'd need something else. Right now we'll use tildes

[madonuko]

Tildes serve a specific purpose in RPM versioning

Yes, ~ just means it is having a version lower than what is specified on the left. For example: 1.2.3~abc is lower than 1.2.3.

use a hyphen instead

You can't.

Another option is to incorporate the + sign

it doesn't have the same effect as ~, thought I guess you could argue if the effect is necessary.

[sadlerm4]

tildes are reserved for specifying the release only, so you'd need something else. Right now we'll use tildes

@korewaChino As mado said, tildes are reserved for sorting a version lower than its major version, i.e. 1.2.0~pre1 sorts lower than 1.2.0.

20240817.git~abcdefg makes zero sense in this context.

[sadlerm4]

For example: 1.2.3~abc is lower than 1.2.3.

So this format 20240812.git~abcdefg is supposed to signify there could be a 20240812.git package version that could sort higher? It's nonsensical.

[madonuko]

maybe it's time to rethink about this again?

[madonuko]

new docs are live now