[RFC] Versioning strategy and release process

[machshev]

We need a versioning strategy and release process so that we can generate Python packages that can be referenced by OpenTitan and any other project that wants to make use of the DVSim tool.

Automated Semantic Versioning

Probably the easiest solution is to use something like: https://python-semantic-release.readthedocs.io/en/latest/
This avoids questions of when and who should be responsible for doing a release. Instead, releases would be automatically be generated in CI for every PR merged.

This tool will automatically determine the package version based on the format of the commit messages since the last release. There are different commit parsers that support different commit conventions.

The basic idea is that PRs that merge a set of commits with fix: ... or perf: ... would be a patch release. While if the commit set contained a feat: ... then this would be a minor version bump. For commits that contain an exclamation mark feat!: ... or an explicit footer line BREAKING CHANGE: ...reason, this would denote a major release.

[rswarbrick]

Just making sure that I understand: I assume that we're imagining some auto-generated file that gets committed into the repository. If the current version is 1.2.3 and I have a PR with 2 commits that should be considered a patch version, are we imagining that the merge process generates an extra commit at the end that bumps the stored version to 1.2.4 (on the rebased version)?

This is kind of new to me, but sounds sensible, I think.

[machshev]

Yes something like that. We might need the extra commit, we might not... I'll try and put together a prototype when I've got some free time.

The automated versioning systems I've used in the past generally rely on tags. So what I was thinking was more on the lines of, enabling merge queue and then:

Pre merge CI

1. Linting checks
2. Unit tests

Merge CI

1. Linting checks
2. Unit tests
3. Take the commit messages from the last release tag, and then use those to determine major/minor/patch.
4. Build the python wheel package
5. Create a new release tag
6. Create a new github release
7. Publish the package to pypi

[machshev]

After looking at the tool in more detail, it looks like the commit header format we use in OT would need a custom parser. We could differentiate between minor version at patch by matching on fix or Fix anywhere in the commit header.

Alternatively we could take the opportunity to start using something like conventional commits? #6

[rswarbrick]

I propose:

• Use python-semantic-release to figure out the "current version" implied by the head of the repo.
• If this is different from the version in pyproject.toml (or if the last commit touched the version), amend the top commit to bump the version in that file to match the "inferred version".

For the parsing part, I propose that we use "conventional commits". Neatly, this can interoperate nicely with the OpenTitan style. For example, a feature change would look like feat: [api] blah. The default conventional commit schema wouldn't know that the "scope" is "api", but we're just adding some extra information for humans that the tool needn't care about.

Note that this is different from OpenTitan style because we're prefixing with things like fix: or feat: (to determine the version bump). But that doesn't seem like an unreasonable addition and the format should still look pretty "normal" to someone in OpenTitan land.