Skip to content

[RFC] Versioning strategy and release process #4

Description

@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.

Activity

  1. pinned this issue on Jul 23, 2025
  2. changed the title [-]Versioning strategy and release process[/-] [+][RFC] Versioning strategy and release process[/+] on Jul 28, 2025
  3. rswarbrick commented on Aug 15, 2025

    @rswarbrick
    Contributor

    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.

  4. machshev commented on Aug 18, 2025

    @machshev
    CollaboratorAuthor

    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
  5. machshev commented on Aug 18, 2025

    @machshev
    CollaboratorAuthor

    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

  6. rswarbrick commented on Aug 22, 2025

    @rswarbrick
    Contributor

    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.

  7. self-assigned this
    on Aug 22, 2025
  8. hcallahan-lowrisc commented on Oct 2, 2025

    @hcallahan-lowrisc
    Contributor

    I think there are probably some things left to do before fully closing this issue.

    • In-tree documentation about the release process for maintainers & expected commit style for contributors
    • CI enforcing the use of conventional-commits
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

help wantedExtra attention is needed

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions