Migrate to uv and integrate PSR for automated releases #218

seansica · 2025-12-23T13:36:08Z

Changes

Replace poetry with uv
Add pre-commit
- pre-commit runs ruff-format for formatting files
  - The changes to Python files in this PR are just ruff formatting applied
- pre-commit runs commitizen for enforcing conventional commit syntax before commits are accepted
Add Python Semantic Release (PSR) for automating SemVer tagging and GitHub releases
- Note: PSR is a highly popular fork of the original semantic-release tool
- Though semantic-release can technically be used within any language environment, it relies on community plugins, and there are only two plugins listed on the official plugins page that support Python or uv; neither of which have many GitHub Stars.
- PSR, on the other hand, seems to have a thriving community, and is purpose-built specifically for Python.
- PSR can run locally and on CI/CD pipelines.
- The only thing that PSR cannot do is commit linting (e.g., "check every commit since the last release"). For this, we use commitizen. This is the equivalent of using semantic-release and commitlint in our other JS-oriented projects.
Refactor CI/CD pipeline to build/publish with uv and PSR (un-tested)
Add Justfile for streamlining common functions (equivalent of npm run ... $$\rightarrow$$ just ...)

- Replace Poetry with uv for dependency management and packaging - Add pre-commit hooks for ruff (lint/format) and commitizen (commit-msg) - Configure Python Semantic Release (PSR) for automated versioning - Add commitizen for local commit message validation - Create unified CI workflow with lint, test, and release jobs - Add Justfile for common development workflows

jondricek

Ok, here's my overarching review. It is definitely going in the right direction but has a few edges that need sanding off.

jondricek · 2025-12-23T16:15:58Z

.github/workflows/ci.yml

+
+      - name: Check commit messages
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then


I want to make sure we make it as easy as possible for external contributors to contribute. This makes me think of this FAQ from the Conventional Commits site.

https://www.conventionalcommits.org/en/v1.0.0/#do-all-my-contributors-need-to-use-the-conventional-commits-specification

Do all my contributors need to use the Conventional Commits specification?
No! If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they’re merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge.

I think it might be better to squash commits from pull requests somehow instead and only validate commit messages that we ourselves write, to not make it an overly arduous process for external contribs.

.github/workflows/ci.yml

.pre-commit-config.yaml

jondricek · 2025-12-23T17:09:59Z

.readthedocs.yaml

-      - pip install poetry
-    post_install:
-      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs
+  commands:


according to the readthedocs docs, we should lean towards using build.jobs stuff instead

https://docs.readthedocs.com/platform/stable/config-file/v2.html#build-commands

we recommend using build.jobs instead

I think I implemented build.jobs correctly but it's possible I assigned the commands to the incorrect build stages.

https://docs.readthedocs.com/platform/stable/builds.html

https://docs.readthedocs.com/platform/stable/build-customization.html

justfile

jondricek · 2025-12-23T17:28:04Z

pyproject.toml

+    "check-wheel-contents>=0.6.1",
+    "commitizen>=4.9.1",
+    "pre-commit>=4.0.0",
+    "pytest>=8.4.2",


pytest is 9.0.2 on PyPI

I think in general we should run uv sync --upgrade after this pull request is merged to update package dependencies that can be upgraded

pyproject.toml

A few more findings

sonarqubecloud · 2025-12-24T17:34:06Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

jondricek

Oh, interesting - it didn't share these comments yet

jondricek · 2025-12-24T17:06:46Z

.github/workflows/ci.yml

+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+


Suggested change

- name: Install the latest version of uv

uses: astral-sh/setup-uv@v7

with:

version: "latest"

- name: Set up Python

run: uv python install ${{ matrix.python-version }}

- name: Install the latest version of uv

uses: astral-sh/setup-uv@v7

with:

python-version: ${{ matrix.python-version }}

jondricek · 2025-12-24T17:07:10Z

.github/workflows/ci.yml

+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+


Suggested change

- name: Install the latest version of uv

uses: astral-sh/setup-uv@v7

with:

version: "latest"

- name: Set up Python

run: uv python install ${{ matrix.python-version }}

- name: Install the latest version of uv

uses: astral-sh/setup-uv@v7

with:

python-version: ${{ matrix.python-version }}

jondricek · 2025-12-24T17:07:37Z

.github/workflows/ci.yml

+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+


Suggested change

- name: Install the latest version of uv

uses: astral-sh/setup-uv@v7

with:

version: "latest"

- name: Set up Python

run: uv python install ${{ matrix.python-version }}

- name: Install the latest version of uv

uses: astral-sh/setup-uv@v7

with:

python-version: ${{ matrix.python-version }}

jondricek · 2025-12-24T17:08:06Z

.github/workflows/ci.yml

+      - name: Setup | Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Setup | Install Python
+        run: uv python install ${{ matrix.python-version }}
+


Suggested change

- name: Setup | Install uv

uses: astral-sh/setup-uv@v5

with:

version: "latest"

- name: Setup | Install Python

run: uv python install ${{ matrix.python-version }}

- name: Setup | Install uv

uses: astral-sh/setup-uv@v7

with:

python-version: ${{ matrix.python-version }}

jondricek · 2025-12-24T17:23:48Z

pyproject.toml

+[tool.semantic_release.branches.main]
+match = "(main|master)"
+prerelease = false
+
+[tool.semantic_release.remote]
+type = "github"
+
+[tool.semantic_release.publish]
+upload_to_vcs_release = true
+


I think we can safely delete these sections since they are very close to the defaults (or exactly the defaults) already, and I don't think we're doing anything special with the prerelease_token

https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html#branches

Suggested change

[tool.semantic_release.branches.main]

match = "(main|master)"

prerelease = false

[tool.semantic_release.remote]

type = "github"

[tool.semantic_release.publish]

upload_to_vcs_release = true

jondricek · 2025-12-24T17:24:21Z

pyproject.toml

+[tool.semantic_release.commit_parser_options]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+allowed_tags = ["feat", "fix", "perf", "build", "chore", "ci", "docs", "style", "refactor", "test"]


Suggested change

allowed_tags = ["feat", "fix", "perf", "build", "chore", "ci", "docs", "style", "refactor", "test"]

allowed_tags = ["feat", "fix", "perf", "build", "chore", "ci", "docs", "style", "refactor", "revert", "test"]

seansica added 3 commits December 22, 2025 16:17

build: update ruff-pre-commit config

599170d

style: apply ruff formatting

708e245

seansica self-assigned this Dec 23, 2025

seansica added 3 commits December 23, 2025 08:49

Merge branch 'main' into semantic-release

0b57c82

build: update uv.lock

c6e8807

build: update read-the-docs config to use uv

5141c5d

jondricek requested changes Dec 23, 2025

View reviewed changes

seansica and others added 9 commits December 23, 2025 13:52

ci: small improvements to ci-cd uv build process

02278d5

chore(pre-commit): bump commitizen to 4.10.1

3c496a9

ci: set python version with a matrix

d0494b7

chore(ci): upgrade setup-uv to v7

8dd5a29

build(read-the-docs): migrate to build.jobs

f981996

build: replace hatch build backend with uv

6e075c2

ci: unset git_committer_name and email in PSR step

35c6552

build(just): add upgrade script

634f249

Apply suggestions from code review

abd4a7b

A few more findings

jondricek reviewed Dec 24, 2025

View reviewed changes

	allowed_tags = ["feat", "fix", "perf", "build", "chore", "ci", "docs", "style", "refactor", "test"]
	allowed_tags = ["feat", "fix", "perf", "build", "chore", "ci", "docs", "style", "refactor", "revert", "test"]

Migrate to uv and integrate PSR for automated releases #218

Are you sure you want to change the base?

Migrate to uv and integrate PSR for automated releases #218

Uh oh!

Conversation

seansica commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

jondricek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonarqubecloud bot commented Dec 24, 2025

Quality Gate passed

Uh oh!

jondricek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

seansica commented Dec 23, 2025 •

edited

Loading