Feature request: Calculate 'version_str' from SCM (source code management)

[marble]

From Slack thread https://app.slack.com/client/T024TUMLZ/G317HUVPT/thread/G317HUVPT-1650007132.025399
2022-04-20

Task

Some documentation is alrways rendered from, for example, the main branch. In Setting.cfg therefore we have version=main (development) or maybe 7.1.1, in case this was the most recent release. This appears in the rendered page but doesn't convey much information, as it doesn't tell anything about the latest release. Mitigation would be to calculate a "real" version number from all the information that is contained in the SCM, mainly Git. But how? This is difficult stuff.

Exploration

Turns out: it can be done. Try this, using the DRC (Docker Rendering Container). Try this for Linux, Mac, WSL2:

mkdir -p ~/kannweg
cd ~/kannweg
git clone https://github.com/TYPO3-Console/TYPO3-Console
cd ~/kannweg/TYPO3-Console

eval(docker run --rm t3docs/render-documentation show-shell-commands)
dockrun_t3rd --help    # <- if you're looking for help
dockrun_t3rd bashcmd 'cd /PROJECT; python -m setuptools_scm'

Final exit status: 0 (completed)

Guessed Version 7.1.2.dev11+gff1732c

What has happened, what does this mean?

We cloned the repo, then switched into the container and found the repo in /PROJECT in read-only mode. Then we ran the Python module setuptools_scm, that had a look at the repo. The tool saw that 7.1.1 was the latest release and guessed, what would be a good version string for the current state. While Settings.cfg still has 7.1.1, as that was the latest release, we have actually progressed to something like 7.1.2.dev11+gff1732c in the main branch, which would be a better choice for the rendering lf the main branch.

Want to experiment?

# go to the commit that follows the 7.1.1 tag
git checkout 0ee0be2

# set a dev tag
git tag 8.0.dev

# check what setuptools_scm guesses on this basis
Final exit status: 0 (completed)

Guessed Version 8.0.dev9+gff1732c