Version management workflow

[paolodina]

• I have searched the issues of this repo and believe that this is not a duplicate.

Issue

Hi, thanks for this wonderful tool, it's a very nice starting point for my projects.

I just wonder how the release process could be. I mean, with poetry version I can bump the version defined in pyproject.toml -> [tool.poetry] -> version, but I wonder how to update the TAG file as well, automatically. And also, how to refresh CHANGELOG.md accordingly with (semantic) commit messages?

Any recommended workflow?

UPDATE:
btw, I also see we have a version.py to keep up-to-date.

[rszamszur]

Good thing you brought this up. Version management could definitely be improved. At the time being, release and version bump is all manual labor. But since releasing is not done often, it wasn't a big priority on the to-do list.

Currently, the version is being tracked in 3 files:

1. pyproject.toml

The version of the package (Main and most important).

2. TAG

Only used for the container image build. make image target doesn't require python nor project installed. So python can not be used for version extraction. Moreover, a bash command like:
sed -n 's/^ *version.*=.*"\([^"]*\)".*/\1/p' pyproject.toml
could have some corner cases that could break the usage, and with this project, I try to aim at the best reproducibility possible. Since, at the time, I didn't have better ideas, this is just a plain text file with a version.

TAG could be easily replaced with an environment variable. If this variable is not set, first try extracting the version from pyproject.toml. If failed, use latest (or even without version extraction; default always as latest).

3. package_name/version.py

This file is just for the sake of application RunTime (for FastAPI constructor, printing version in docs, etc.). I was thinking of extracting it somehow via tomllib or pkg_resources. But again, I felt this could jeopardize project reproducibility (not mentioning it would be additional runtime dependency).

Not yet sure how to get rid of the hardcoded version.py.

[paolodina]

I'd appreciate your opinion on this.

I feel like I'm overlooking something, but if we create a new release.sh script in build/ which:

• use poetry version to update version in pyproject.toml out-of-the-box
• get the new assigned version (output of poetry version -s)
• update TAG accordingly
• update package_name/version.py accordingly

The script should accept "the bump rule to update the version" (patch, minor, major, etc) as a parameter, or no params (in this case it could output the same of poetry version or poetry version -s).

Also considering that poetry is part of fastapi-mvc pre-requisites, so no additional dependencies are required, wouldn't this do the trick?

Update: hypotetical related GitHub actions https://github.com/rochacbruno/fastapi-project-template/blob/main/.github/workflows/release.yml, https://github.com/commitizen-tools/commitizen/blob/master/.github/workflows/bumpversion.yml, etc

---

$ poetry version -h
USAGE
  poetry version [-s] [<version>]

ARGUMENTS
  <version>              The version number or the rule to update the version.

OPTIONS
  -s (--short)           Output the version number only

GLOBAL OPTIONS
  -h (--help)            Display this help message
  -q (--quiet)           Do not output any message
  -v (--verbose)         Increase the verbosity of messages: "-v" for normal output, "-vv" for more verbose output and
                         "-vvv" for debug
  -V (--version)         Display this application version
  --ansi                 Force ANSI output
  --no-ansi              Disable ANSI output
  -n (--no-interaction)  Do not ask any interactive question

DESCRIPTION
  The version command shows the current version of the project or bumps the version of
  the project and writes the new version back to pyproject.toml if a valid
  bump rule is provided.
  
  The new version should ideally be a valid semver string or a valid bump rule:
  patch, minor, major, prepatch, preminor, premajor, prerelease.

[rszamszur]

The way I see it, a script for bumping version could be implemented in two ways (at least at first glance).

First is what you've proposed. This would definitely work and would be pretty easy to implement thanks to the poetry bump version feature (btw., I wasn't aware of this, thanks for bringing it to my attention!) Few notes from my site:

release.sh script in

Maybe name bump-version.sh or similar to avoid confusion since this script would only bump the project version?

or no params (in this case, it could output the same of poetry version or poetry version -s)

Wouldn’t poetry version -s’ print a current project version? Maybe the parameter could be required or have patch` as a default value?

Other than that, I think it's good to go.

A quick draft (I haven't actually run this):

#!/usr/bin/env bash

if [ -n "$DEBUG" ]; then
	set -x
fi

set -o errexit
set -o nounset
set -o pipefail

POETRY_HOME="${POETRY_HOME:=${HOME}/.poetry}"
"$POETRY_HOME"/bin/poetry version "$1"
VERSION=$("$POETRY_HOME"/bin/poetry version -s)
echo "$VERSION" > TAG
# package_name needs to be somehow extracted.
# One can find this value in `fastapi-mvc.ini` file under the project root.
cat << EOT > package_name/version.py
"""fastapi-mvc-example version."""
__version__ = "$VERSION"
EOT

Tradeoffs:

• Some people may argue it's a dependency inversion. One needs poetry to bump the project version into specific files. At the same time, Coreutils are sufficient to implement such a script.
• Getting the value of package_name could get tricky and have some edge cases.

The second option would be using just Coreutils. You either provide a version as a parameter or have one plain text file with the version. And then just run sed on files that need to be updated.

Tradeoffs:

• sed command for replacing version can have some edge cases.
• The value of package_name needs to be extracted as well.

[rszamszur]

A third option could be implementing this as fastapi-mvc CLI command. The parser class for fastapi-mvc.ini file is already implemented. The command could take either a string or semver bump rule. Lastly, update the version in appropriate files.
In the case of semver approach, a method for bumping would be required. But, for starters, I'd go with a plain string CLI argument. Whatever you will provide, you will get as a version.

[paolodina]

Thanks for the explanation! 🙏

I already configured a bump command for make very similar to yours and it works well. I'd like to contribute with some sort of PR, but as Mr. obvious always says: time is scarce. Because there would be something more to clarify and decide. Anyway, this ticket will stay as a draft reference, feel free to keep it open or close as you want.

[rszamszur]

No problem, glad you have this sorted.

As it goes to the actual feature for bumping version, I will create an issue for that with implementation details within a few days. But first, I need to test a few solutions. I'll let you know once it's ready if you'd like to contribute.