Adopt bump2version for automating version bumps

[minrk]

Removes manual edit & commit & tag steps from the release process.

cf jupyterhub/team-compass#213 (comment)

/cc @manics

[consideRatio]

A merge conflict caused duplication of files as well as some adjustments to the instructions: dev-requirements.txt and requirements-dev.txt.

[minrk]

Thanks, rebased

[consideRatio]

I think I've read up enough about bump2version now to grasp it!

My understanding

bump2version bumps one version part (for example: major, minor, patch, release_name, release_number) and reset latter version parts to their initial values. If a value is an omittable omittable value, which the initial value among the values is by default, and there is a serialize template where it can be unused used, this version part will be omitted.

This PR opts to work with four version parts, <major>.<minor>.<patch>.<release>, and allow release to have the value of dev and stable, and we make stable an omittable value. I think this makes sense, the key question I have is regarding if we want to have an initial release part value of dev or stable. This couples to some different patterns of using bump2version and what it means to have .dev suffixed to the chart version.

If we use the dev as the initial value of the release part, a bump2version major bump would give us for example 1.0.0.dev, while if we have stable as the initial value of the release part, we would get 1.0.0.

If dev comes before stable

# assuming:
# 1. we are on 0.4.4.dev
# 2. the release part values are ordered: dev, stable

# either bump patch and return to dev
bump2version --tag release # 0.4.4
bump2version patch # 0.4.5.dev

# or bump minor and return to dev
bump2version --no-commit minor # 0.5.0.dev
bump2version --tag release # 0.5.0
bump2version patch # 0.5.1.dev

# or... we explicitly specify the version
# when doing this, it does not matter what part
# name we specify so using - instead of it makes
# some sense to not fool others it matters
VERSION=0.4.4
bump2version --tag --new-version $VERSION - # 0.4.4
bump2version patch # 0.4.5.dev

If stable comes before dev

# assuming:
# 1. we are on 0.4.3.dev
# 2. the release part values are ordered: stable, dev

# we have surpassed the stable version for this patch and
# cannot return without explicitly setting --new-version
bump2version --tag --new-version 0.4.3 -
bump2version --no-commit patch # 0.4.4
bump2version release # 0.4.4.dev

# to bump minor and return to dev is more forgiving
bump2version --tag minor # 0.5.0
bump2version --no-commit patch # 0.5.1
bump2version release # 0.5.1.dev

My takeaways

• I find bump2version main help is to read and write a version to a file, make git tags, and make commits.
• I find the practice of bumping the patch version and appending a pre-release of .dev following a release makes it harder to use bump2version in a way that that complies with that practice.

My suggestions

I now like the idea of updating the instructions where we use bump2version in order to make a tag do it something like this.

# optional: to make a major or minor release, first bump
bump2version --no-commit <major | minor>

# bump .dev to stable and tag
bump2version --tag release

# increment patch and go back to .dev
bump2version patch

OUTDATED: as @manics made me think otherwise in discussion here: #74 (comment)
I'm not sure, but assuming we adopt bump2version and the practice of bumping the patch version and appending .dev after releases, I think we should use the approach of manually and explicitly setting the version. In other words, this flow.

# tag a release
VERSION=0.4.4
bump2version --tag --new-version $VERSION - # 0.4.4

# increment patch and append .dev
bump2version patch # 0.4.5.dev

Related thoughts

Does bump2version fit into a CD pipeline somehow? Hmmm, no I don't think so, as a CD pipeline job to that would modify the git history would be a bad idea! I figure it could lead to pipelines triggering pipelines etc. No, I don't see a way to benefit from bump2version when used by scripts unless for extracting the current version or similar.

[consideRatio]

@minrk - the current state of the PR looks good to me now that I grasp things better than I originally did. I got quite confused about using a tool like bump2version to set a version explicitly with VERSION=.... What I didn't grasp fully is that it's value mainly isn't to figure out the version to set, but to update in-code related versions based on the implicit or explicitly decided version.

This is why it felt important for me to figure out a way to not set the version explicitly, but I find doing it like below is quite complicated and requires confirmation of doing it right anyway so I'm happy with the current approach in the PR.

# optional: to make a major or minor release, first bump it up
bump2version --no-commit <major | minor>

# bump .dev to stable and tag
bump2version --tag release

# increment patch and go back to .dev
bump2version patch