chore: modernize Python repo to uv + pyproject.toml by farhan · Pull Request #329 · openedx/django-wiki

farhan · 2026-09-24T09:59:14Z

Important

Written with the assistance of Claude Code, human-reviewed before posting.

Modernize django-wiki
Part of openedx/public-engineering#506

Summary

Package is published to PyPI as openedx-django-wiki.
Move the wiki and django_notify packages into a src/ layout; the testproject/wiki and testproject/django_notify symlinks now point to ../src/*.
Replace setup.py with pyproject.toml (PEP 621 static metadata) and set requires-python = ">=3.12" (pyproject.toml:8); edx_release had no python_requires and already tested only on 3.12.
Switch from pip-compile to uv with PEP 735 dependency groups (pyproject.toml:48-75) and commit uv.lock.
Add a docs tox env (tox.ini:15-21) and CI job (.github/workflows/ci.yml:16).
Update CI to use astral-sh/setup-uv and SHA-pin all actions.
Add python-semantic-release and .github/workflows/release.yml (OIDC trusted publishing), releasing from edx_release.
Mark CHANGELOG.md as deprecated (CHANGELOG.md:1); release notes now live on GitHub Releases.

Removed/Updated

Deleted files: setup.py, requirements/, openedx.yaml (legacy OEP-2 metadata), .github/workflows/pypi-publish.yml (superseded by release.yml)

Updated Makefile targets:

Target	Change
`upgrade`	pip-compile commands replaced with `edx_lint write_uv_constraints pyproject.toml` + `uv lock --upgrade` (`Makefile:3-5`)
`test`	New; runs `pytest --cov wiki --cov django_notify` from `testproject/` (`Makefile:7-8`); called by the `django42`/`django52` tox envs
`docs`	New; runs `make -C docs html` (`Makefile:10-11`); called by the `docs` tox env

Versioning

setuptools-scm with dynamic = ["version"] (pyproject.toml:33) and fallback_version = "0.0.0.dev0" (pyproject.toml:109). edx_release had a PyPI publish workflow; python-semantic-release now controls the version string at release time via git tags. The latest tag v3.1.2 matches the latest PyPI release, so it is the release baseline. src/wiki/__init__.py exposes __version__ via importlib.metadata.

Important Notes

Default branch is edx_release, not master. .github/workflows/release.yml targets edx_release in all 3 places (push trigger at line 5, if: guards at lines 14 and 70), and pyproject.toml:103-104 adds [tool.semantic_release.branches.edx_release], because PSR only releases from main/master by default. Without this, the release job would pass and publish nothing. Feanil agreed with this approach in chore: modernize Python repo to uv + pyproject.toml #329 (comment).
.github/workflows/ci.yml drops the push: branches: [master] trigger. release.yml calls ci.yml via workflow_call, so a push trigger would run CI twice on every merge (see platform-plugin-aspects#257).
.github/workflows/ci.yml keeps the workflow name Python CI for parity. --locked is used only on uv sync (line 31), not on uv run. There is no fetch-depth: 0, no secrets: inherit and no Codecov step.
CI check names change from Tests (ubuntu-latest, 3.12, djangoXY) to docs, django42 and django52. The only required status check on edx_release is openedx/cla, so no required checks are affected.
pyproject.toml metadata matches setup.py except authors, which uses the org-standard Open edX Project <oscm@openedx.org> (as in openedx/sample-plugin and build: modernize Python packaging to uv + pyproject.toml (PEP 621) openedx-atlas#78) instead of Benjamin Bach. It keeps the same classifiers including Operating System :: OS Independent, and no Natural Language / Python :: 3 classifiers. The License :: OSI Approved :: GNU General Public License v3 (GPLv3) classifier is dropped in favour of the PEP 639 license = "GPL-3.0-only" expression (pyproject.toml:9).
The README settings link now points to src/wiki/conf/settings.py (README.md:79), and the Development setup step now uses uv sync --group dev instead of pip install -r requirements.txt (README.md:130).
MANIFEST.in excludes testproject/ and repo-only files (pylintrc, catalog-info.yaml, model_chart_wiki.pdf, CHANGELOG.md, TODO.md, uv.lock) from the sdist.
Wheel parity was checked by building the wheel from edx_release and from this branch. With include-package-data = false (pyproject.toml), the PR wheel has the same files as the 3.1.2 wheel on PyPI. Requires-Dist is unchanged.

Out of Scope

Item	Notes	Next action
pylint `quality` env	`edx_release` never ran pylint in tox, the Makefile or CI, so no `quality` env is added (parity). `pylintrc` is kept.	Follow-up PR: fix pylint errors in the code base, then add `quality` as a real gate

Testing Notes

Note: PR creator has tested the PR via CI and building the packages manually. No manual testing has been done to test the repo features. It will be great if the repo owner could test it.

🤖 Generated with Claude Code

…0 and Test#445 Test#180 now verifies release.yml's push branch matches the repo's actual default branch (via gh repo view) and flags the mismatch with a concrete fix instruction. Repos like django-wiki use edx_release, not master, so the standard template would silently never release. Test#445 gains a note that a dead push trigger (wrong branch name) masks the double-run bug — both tests must be fixed together when the default branch is not master. References: - openedx/platform-plugin-aspects#257 (original double-run fix) - openedx/django-wiki#329 (first non-master default branch case) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

farhan · 2026-10-06T11:19:03Z

Caution

release.yml targets master — auto-releases will never fire after this PR merges

This repo's default branch is edx_release. The master branch exists but has had no commits since November 2014 — all development merges into edx_release.

Why this is a breaking change: The existing pypi-publish.yml (deleted by this PR) triggered on on: release: types: [published] — a manually created GitHub Release. That flow worked regardless of branch name. This PR replaces it with PSR auto-release on push to a branch. That branch is master, which never receives commits, so PSR will never run and PyPI publishing is effectively broken from day one after merge.

As currently written, release.yml listens on branches: [master] and guards both the release and publish_to_pypi jobs with if: github.ref_name == 'master'.

Fix: Update the three occurrences in .github/workflows/release.yml:

on.push.branches: [master] → [edx_release]
if: github.ref_name == 'master' (×2) → 'edx_release'

@feanil -- Can you please look/share your thoughts into this issue or tag the relevant maintainer

feanil · 2026-10-07T17:20:46Z

That makes sense to me.

farhan · 2026-10-10T05:29:21Z

+requires-python = ">=3.12"
+license = "GPL-3.0-only"
+license-files = ["src/wiki/COPYING", "src/django_notify/COPYING"]
+authors = [


@feanil FYI: this PR changes the package author from Benjamin Bach <benjamin@overtag.dk> (edx_release setup.py) to the org-standard Open edX Project <oscm@openedx.org>.

irfanuddinahmad

Before merging, a PyPI owner needs to add a trusted publisher for this repo with workflow release.yml. Earlier releases used an API token, so the first OIDC publish will fail without it.

irfanuddinahmad · 2026-10-13T17:28:45Z

@@ -0,0 +1,84 @@
+name: Release


Please replace release.yml with sample-plugin's current release.yml, dropping only the monorepo lines (directory:, the tutor build step, the extra publish jobs, packages-dir:). The pins and logic already match, but the workflow name, step names, run: | style and comments differ; keeping it identical makes future syncs a plain diff.

…0 and Test#445 Test#180 now verifies release.yml's push branch matches the repo's actual default branch (via gh repo view) and flags the mismatch with a concrete fix instruction. Repos like django-wiki use edx_release, not master, so the standard template would silently never release. Test#445 gains a note that a dead push trigger (wrong branch name) masks the double-run bug — both tests must be fixed together when the default branch is not master. References: - openedx/platform-plugin-aspects#257 (original double-run fix) - openedx/django-wiki#329 (first non-master default branch case) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

irfanuddinahmad · 2026-10-16T13:42:48Z

-        TOXENV: ${{ matrix.toxenv }}
-      run: tox
+      - name: Run tox
+        run: uv run tox -e ${{ matrix.toxenv }}


Please use uv run --locked tox -e ${{ matrix.toxenv }}. Without --locked, uv run silently re-locks when uv.lock is stale instead of failing. It also matches i18n-tools, codejail-includes and platform-plugin-aspects.

We are already using --locked here
No need to use it with uv run

irfanuddinahmad · 2026-10-16T13:42:48Z

+]
+
+[tool.setuptools]
+include-package-data = true


With include-package-data = true, setuptools-scm also sweeps wiki/COPYING, django_notify/COPYING, django_notify/README.md, wiki/plugins/images/static/wiki/colorbox/README.md and wiki/plugins/notifications/TODO.md into the wheel, which 3.1.2 didn't ship. Setting it to false keeps the wheel identical to 3.1.2, since package-data already covers the assets.

done, thanks for flagging it

…0 and Test#445 Test#180 now verifies release.yml's push branch matches the repo's actual default branch (via gh repo view) and flags the mismatch with a concrete fix instruction. Repos like django-wiki use edx_release, not master, so the standard template would silently never release. Test#445 gains a note that a dead push trigger (wrong branch name) masks the double-run bug — both tests must be fixed together when the default branch is not master. References: - openedx/platform-plugin-aspects#257 (original double-run fix) - openedx/django-wiki#329 (first non-master default branch case) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

farhan · 2026-10-20T09:43:15Z

@irfanuddinahmad The PR is available for the next pass.

irfanuddinahmad

LGTM, thanks!

Move packaging to pyproject.toml with a src/ layout, uv for dependency management, and python-semantic-release for automated releases, per the Open edX Python modernization effort. Releases run from edx_release, the repo's default branch, since master has had no commits since 2014; edx_release gets its own PSR release group so merges actually publish. Non-package files are excluded from the sdist and the original package keywords are kept, preserving parity with the setup.py-built distribution. CHANGELOG.md is marked deprecated now that release notes live on GitHub Releases. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

farhan mentioned this pull request Sep 24, 2026

Modernize Python repo | Django Apps & Plugins openedx/public-engineering#512

Open

25 tasks

farhan force-pushed the farhan/modernize-python-repo branch from 3f650dc to 3d80bf7 Compare October 6, 2026 06:59

farhan force-pushed the farhan/modernize-python-repo branch from caac099 to 3b83232 Compare October 6, 2026 15:45

farhan force-pushed the farhan/modernize-python-repo branch from 7e73e7e to 6f61e83 Compare October 8, 2026 06:55

farhan marked this pull request as ready for review October 8, 2026 11:19

farhan force-pushed the farhan/modernize-python-repo branch from e10372c to 1096812 Compare October 9, 2026 16:29

farhan commented Oct 10, 2026

View reviewed changes

irfanuddinahmad reviewed Oct 13, 2026

View reviewed changes

irfanuddinahmad reviewed Oct 16, 2026

View reviewed changes

farhan force-pushed the farhan/modernize-python-repo branch 2 times, most recently from 9fd3a36 to 381301b Compare October 20, 2026 07:21

farhan requested a review from irfanuddinahmad October 20, 2026 07:32

farhan force-pushed the farhan/modernize-python-repo branch from 381301b to 31d9c0e Compare October 20, 2026 08:09

irfanuddinahmad approved these changes Oct 20, 2026

View reviewed changes

farhan force-pushed the farhan/modernize-python-repo branch from 31d9c0e to 95846bc Compare October 27, 2026 07:43

feanil approved these changes Oct 28, 2026

View reviewed changes

feanil merged commit 3a29963 into openedx:edx_release Oct 28, 2026
5 checks passed

Navigation Menu

Repository navigation

chore: modernize Python repo to uv + pyproject.toml - #329

chore: modernize Python repo to uv + pyproject.toml#329
feanil merged 1 commit into
openedx:edx_releasefrom
farhan:farhan/modernize-python-repo

farhan commented Sep 24, 2026 •

edited by feanil

Loading

Uh oh!

farhan commented Oct 6, 2026 •

edited

Loading

Uh oh!

feanil commented Oct 7, 2026

Uh oh!

farhan Oct 10, 2026

Uh oh!

irfanuddinahmad left a comment

Uh oh!

irfanuddinahmad Oct 13, 2026

Uh oh!

irfanuddinahmad Oct 16, 2026

Uh oh!

farhan Oct 20, 2026

Uh oh!

irfanuddinahmad Oct 16, 2026

Uh oh!

farhan Oct 20, 2026

Uh oh!

farhan commented Oct 20, 2026

Uh oh!

irfanuddinahmad left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

farhan commented Sep 24, 2026 • edited by feanil Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Removed/Updated

Versioning

Important Notes

Out of Scope

Testing Notes

Uh oh!

farhan commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

feanil commented Oct 7, 2026

Uh oh!

farhan Oct 10, 2026

Choose a reason for hiding this comment

Uh oh!

irfanuddinahmad left a comment

Choose a reason for hiding this comment

Uh oh!

irfanuddinahmad Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

irfanuddinahmad Oct 16, 2026

Choose a reason for hiding this comment

Uh oh!

farhan Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

irfanuddinahmad Oct 16, 2026

Choose a reason for hiding this comment

Uh oh!

farhan Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

farhan commented Oct 20, 2026

Uh oh!

irfanuddinahmad left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

farhan commented Sep 24, 2026 •

edited by feanil

Loading

farhan commented Oct 6, 2026 •

edited

Loading