Feature request discussion: Valid semver versions for CD based on tag distance

[reallistic]

Hello thanks for all the hardwork on this lib!

I saw the discussion and resolution for #311 which is pretty good however it creates versions ending in .dev# unless there is an explicit tag. Tags makes a lot of sense for public releases where tags are a good way to snapshot the code at release time for public inspection and recreation. However, for internal/private projects it introduces a (small) bit of friction for releases that don't need the same level of auditing.

I would like to propose adding support for a distance-based semver strategy similar to setupmeta.

I have created a PoC for this here and am happy to open a PR with the changes if this version scheme is considered acceptable.

How this would work (adapted from setupmeta docs):

Every time you commit a change, the number of commits since last git tag will be used to determine the 'patch' part of version.

Example:

Commit	Tag	Version	Note (command ran to add tag)
no .git		0.0.0	Version defaults to 0.0 (when no tag yet)
none		0.0.0+dirty	No commit yet (but git init was ran)
g1		0.0.1	Initial commit, 0.0.1 means default v0.0 + 1 change
g1		0.0.1+dirty	Same as above, only checkout was not clean anymore
g2		0.0.2
g3		0.0.3
g4	v0.1.0	0.1.0	git tag v0.1.0
g5		0.1.1	(1 commit since tag)
g6		0.1.2
g7		0.1.3
g8	v0.2.0	0.2.0	git tag v0.2.0
g9		0.2.1
g10	v1.0.0	1.0.0	git tag v1.0.0
g11		1.0.1
g10	v1.0.2	raise ValueError("invalid tag")	git tag v1.0.2

• Without any tag, version defaults to 0.0.*

• First tag here is v0.1, git describe will yield v0.1.0 (no commits since last tag),
  and scheme will consider version to be 0.1.0 (tag 0.1 with 0 commits)

• A commit occurs and doesn't add a git tag, version for that commit will be 0.1.1
  (tag 0.1 with 1 change since tag)

• A 2nd commit occurs and doesn't add a git tag, version for that commit will be 0.1.2 etc

• Dirty checkouts will get a version of the form 0.1.2+dirty

[RonnyPfannschmidt]

I need a more elaborate example to get this

The heusteric would be wrong for most repos i work on

[RonnyPfannschmidt]

That being said given a appropriate name this can go in

A caveat is that im preparing a breaking release where most code moves into vcs versioning

[reallistic]

I need a more elaborate example to get this

Here is how this works for private projects I work on published to our internal pypi:

CI is configured to publish packages based on successful tests + build of the main branch. Imagine the following progression:

• [v0.0.1] During project scafolding via cookiecutter a commit to main is made with only templated files. It generates a v0.0.1 project that is essentially never used.
• [v0.0.4] A PR is made to the repo with 3 commits adding some implementation. Some alpha code or maybe a prototype. That gets merged and generates a v0.0.4 package which is somewhat useable.
• [v0.0.X] More PRs and iterations to get a stable api. All published as v0.0.X where X is the number of total commits in main
• [v0.1.0] After prototyping, a stable api is found and cemented with code changes or CHANGELOG entry. This PR's final commit is tagged v0.1.0. When the commit is merged to main the first stable version is published at v0.1.0.

After the api is stable consumers are told it exists and encouraged to use it. Alpha/beta testers are told to move to the stable version. This is often done with a min pin.

Moving forward, versions are driven mainly by commit distance from tag. Occasionally a bump will make sense (new major features, breaking change, etc). Those bumps are handled as described above.

Does this all make sense?

given a appropriate name this can go in

What about the name distance? Or more explicit major-minor-distance?

[RonnyPfannschmidt]

Now im more confused about the proposed approach

What you describe is basically the same scheme as we already have but instead of the standardized dev marker for unreleased versions you want to use the normal patch number

[reallistic]

The dev# marker as you named is for development releases however the goal is for these to be considered stable releases. Even though that is not true for versions < 0.1.0 in my example. It would be true for all others. The purpose of this strategy is to treat all releases as stable.

[RonnyPfannschmidt]

So you intent to do a continuous release no tags approach?

[nedbat]

Yes, this is for libraries that should be continuously deployed, every merge to main.

[RonnyPfannschmidt]

That needs some more consideration as adding a tag for each such commit would be in line with the current design

Im slightly uncomfortable with having releases from commits without tags

[nedbat]

It is unusual to have a repo that is deployed as stable for every merge to main. But if the repo owner wants to do that, it's just creating extra work for them to insist that they tag the commit. It would mean that every commit on main is tagged. In my mind, that defeats the purpose of tags, which is to mark special commits. If everything is "special", then why require them all to be marked?

I understand this model would make many people uncomfortable, but it's not being forced on repo owners, it's an option if they want it. setuptools-scm already does a great job accommodating many different models of releasing. This is one more model. It's unusual, but it's not wrong.

[RonnyPfannschmidt]

git does not track enough metadata to reliably implement this model tho - it would work more correct with scm like monotone, fossil or mercurial that keep track of branches in more detail

git doesn’t do that, so the proposed model would break down as branch references get deleted

at least any feature release would need a tag to keep git sane with the information

this is why i consider the model "problematic" - its asking for trouble on a scm thats metadata scarse

[reallistic]

git does not track enough metadata to reliably implement this model

That is a good point. As described the model relies heavily on the committer to do the right thing 100% of the time.
What type of guardrails would you want to see? One that comes to mind is adding the commit sha or a dev type of prefix if the branch != main. Thoughts on that?

[RonnyPfannschmidt]

what i learned from people - is that people and/or their tools will invariably make a mistake

the current default mechanism has that in mind
its not clear to me ohw to apply it to the version scheme you propose without needing tags for everything for at least gt and/ir mmercurial with lightweight branches

[reallistic]

In this way the default does a great job of protecting people from themselves. The strategy proposed here is something folks would opt into with an explicit tradeoff of where you accept some risk and gain some speed. As @nedbat mentioned, it may not be right for everyone but it offers another choice for some who are willing to accept that tradeoff.