Versionista

Note

The code in this repository has been made public as-is for informational purposes. The repository may use private resources for the building and execution of the code. For example, private registries may be used for dependency resolution.

The documentation may refer to restricted URLs.

Versionista is a setuptools_scm plugin.

It follows GDC branching and release conventions to produce PEP-440 versions.

In general terms commits following a tag on the ...

• develop branch will have alpha aN postfix.
• main (or master) branch will have beta bN postfix.
• release branch will have release candidate rcN postfix.
• feature branch will have devN postfix.

These postfix grant different priorities to versions such that aN < bN < rcN < tag consistent with GDC's release process.

See pre-releases and dev-releases.

The following table depicts all cases in detail.

mainbranch = master or main

branch	tag	distance	dirty	result
mainbranch	1.0	0	no	1.0
mainbranch	1.0	3	no	1.1.b3
mainbranch	1.0	0	yes	1.1.b0+dirty
mainbranch	1.0	3	yes	1.1.b3+dirty
develop	1.0	0	no	1.0
develop	1.0	3	no	1.1.a3
develop	1.0	0	yes	1.1.a0+dirty
develop	1.0	3	yes	1.1.a3+dirty
release/branch	1.0	0	no	1.0
release/branch	1.0	3	no	1.1.rc3
release/branch	1.0	0	yes	1.1.rc0+dirty
release/branch	1.0	3	yes	1.1.rc3+dirty
feat/branch	1.0	0	no	1.1
feat/branch	1.0	0	yes	1.1.dev0+dirty
feat/branch	1.0	3	no	1.1.dev3+feat-branch
feat/branch	1.0	3	yes	1.1.dev3+feat-branch-dirty

Usage

  # pyproject.toml
  [build-system]
  requires = [
    "setuptools >= 61",
    "wheel",
    "setuptools_scm[toml]",
+   "versionista",
  ]
  build-backend = "setuptools.build_meta"

  [project]
+ dynamic = ["version"]

...

  [tool.setuptools_scm]
-  local_scheme = "dirty-tag"
+  local_scheme = "versionista-local-format"
+  version_scheme = "versionista-format"

---

🚨 NOTE: Using setup.py is strongly discouraged.

https://setuptools-scm.readthedocs.io/en/latest/usage/

  from setuptools import setup

  setup(
      ...
-     version="...",
+     # version="...",
+     use_scm_version={"version_scheme": "versionista-format"},
      ...
  )

As CLI tool

Running manually should never be needed. Nonetheless:

python -m setuptools_scm

Dev setup

pip install -e ".[dev]"
pip install tox
tox

Note

For gitlab ci, the repo will be checkout in detached head mode. Setuptools_scm will not be able to solve the branch name from git command correctly. We overwrite this behavior by using the env variable from gitlab-ci.