Standardize and automate release flow

[redeboer]

Problem description

Have had a few times that pushing a tag results in a failed deploy job, e.g. https://travis-ci.com/github/ComPWA/expertsystem/jobs/350476070, because I forgot to bump the version in the setup.py file. There are better tools for that, like bumpversion.

Also, we haven't really thought about how to deal with releases. Linear commit history already provides some sort of clean versioning, now it's just a matter of summarising the most important changes for each release. For now, I follow the release style that tensorflow uses. Although we're unclear about Semantic Versioning.

Summary

• Should we use Semantic Versioning?
• How to decide about whether a release is a patch or a minor version update?
• How to make that as effortless (automatic) as possible?
• Which (adr: choose packaging system and versioning scheme #70) conventions to use for the release draft?
• How to keep Git tags in sync with the (single source of truth)
• Should we reconsider our packaging tool/setup (i.e.setup.cfg, pyproject.toml, ...)

This differs from #70 in the sense that in this repository we want to try out and illustrate some tools for a nice release flow. In the PWA Pages we describe that release flow after it turns out to work well. The PWA Pages then serve more as a guideline.

Some resources

• https://packaging.python.org/guides/single-sourcing-package-version/
• https://semver.org/
• https://stackoverflow.com/a/5582128 (on Git and single source of truth for package version)

[spflueger]

Regarding the version of setup.py: The current situation is not ideal, but its fairly ok. Not sure if bumpversion is foolproof. Some kind of hook in github would almost be best, that has access to the tag stage and will deny a tag if the version does not match. Don't know what state of the art is here.

Regarding the versioning: Semantic versioning is nice and I would love to do that (to get some hands on experience with this). But for me that would imply that you keep several major version branches that are maintained simultaneously. So I think that will add to much workload.

[spflueger]

Lets turn this into an ADR, to keep our decision fixed. I think this should almost be ComPWA global, decision...

[redeboer]

If it's global, imho the best place would be
https://github.com/ComPWA/PWA-pages
For instance, a section with thoughts on linear commit history (particularly its use in a research settings), how that facilitates the release flow (the linear commit messages neatly summarise changes), how to tag and bump a version (as you say, probably best through a git hook), and how to draft a release note.

[spflueger]

Yeah exactly. That was my idea. Do you think this decision should be global or project local?

[redeboer]

So a description of the conventions can best be placed in some global place and I can only think of the PWA Pages (even if they're experimental). Git hooks and all have to be implemented for each repo, ofc, but the expertsystem can serve as a nice try-out (particularly with the upcoming pre-releases).

[spflueger]

I meant if the conventions we decide based on the versioning will apply to all subprojects within ComPWA? Also we should keep in mind that tensorwaves will be closely coupled to AmplitTF and zfit.

[redeboer]

Maybe 'guideline' is a better word than 'convention' here.
Anyway, main point is: create an ADR under the expertsystem or under the PWA Pages?

[redeboer]

Now that #102 is through, I think this issue can be fixed by creating something like a __version__ file at the script stage of the Travis deploy job. That file can then be used in the setup.cfg (we have to make sure this doesn't cause errors for users). So the version determination would happen somewhere this stage:

expertsystem/.travis.yml

Lines 56 to 65 in a438784

	- name: "Deploy PyPI package"
	install: echo "Skipping install stage"
	script: echo "Skipping script stage"
	deploy:
	edge: true
	provider: pypi
	on:
	tags: true
	distributions: sdist
	skip_existing: false

And we have to make sure this job is only performed when triggered by a tag.

[spflueger]

https://pypi.org/project/setuptools-scm/ this cant help?

[redeboer]

Yes good one, looks promising, I'll check it out later.