Modernize Python repo: pyproject.toml + uv + semantic-release

[salman2013]

Summary

Modernizes the Python tooling for xblocks-contrib in three phases, aligning with the Open edX org standard established in openedx/sample-plugin.

Ticket: openedx/public-engineering#506

Changes generated by Claude Sonnet 4.6 using the modernize-python-tooling skill, reviewed by Salman.

---

Commits

chore: migrate package metadata to pyproject.toml

• Consolidated all package metadata into pyproject.toml (PEP 621) with static dependencies list and dynamic = ["version"]
• Configured setuptools-scm (version_scheme = "only-version", local_scheme = "no-local-version")
• Updated license to SPDX string format (PEP 639): license = "AGPL-3.0" + license-files = ["LICENSE.txt"]
• Deleted setup.py and setup.cfg

chore: switch dependency management from pip-tools to uv

• Added [dependency-groups] (PEP 735): test-base, test (Django 5.2), django42, quality, doc, ci, dev
• Used [tool.uv].conflicts to allow Django 4.2 and 5.2 to coexist in a single uv.lock with separate resolutions
• [tool.edx_lint].uv_constraints holds repo-specific pins; [tool.uv].constraint-dependencies managed by edx_lint write_uv_constraints
• Rewrote tox.ini to use tox-uv>=1 and uv-venv-lock-runner with dependency_groups
• Updated Makefile: upgrade runs uv lock --upgrade, requirements runs uv sync --group dev
• Updated python-tests.yml: added astral-sh/setup-uv, uv sync --group ci, uv run tox
• Deleted entire requirements/ directory (11 files)

chore: add python-semantic-release and commitlint workflows

• Added [tool.semantic_release] with build_command exporting SETUPTOOLS_SCM_PRETEND_VERSION=$NEW_VERSION before uv build
• Added release.yml: runs python-tests.yml as a reusable workflow, then PSR v10.5.3 on main, publishes to PyPI via OIDC trusted publisher (no token needed)
• Added commitlint.yml: enforces conventional commit format on PRs
• Deleted pypi-publish.yml (was causing duplicate publishes)
• Reverted upgrade-python-requirements.yml to shared openedx/.github reusable workflow
• Updated README.rst with uv-based setup instructions

---

Test plan

• make requirements
• uv run tox -e django42
• uv run tox -e django52
• uv run tox -e docs

[openedx-webhooks]

Thanks for the pull request, @salman2013!

This repository is currently maintained by @openedx/axim-engineering.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[farhan]

@salman2013 Thanks for creating the PR!

I am sharing a review which is done with the help of Claude, please address if you agree:

Consider the standard repo as xblocks-extra after merging of openedx/xblocks-extra#50 and openedx/xblocks-extra#38.

Below are the gaps in PR #251 relative to the standardized xblocks-extra (main + PR 50 + PR 38).

---

1. pyproject.toml

• Quality tooling — biggest gap. The standard uses ruff ([tool.ruff], [tool.ruff.lint], [tool.ruff.format] sections, line-length = 120, target-version = "py312"). PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 keeps the legacy stack: pylint, pycodestyle, pydocstyle, isort (plus root pylintrc / pylintrc_tweaks files). Migrating to ruff would also remove the [tool.isort], [tool.pycodestyle], [tool.pydocstyle] sections.
• Coverage config not in pyproject. The standard has [tool.coverage.run], [tool.coverage.report] (with fail_under = 70), and [tool.coverage.html]. PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 still carries a separate .coveragerc at root — it should move into pyproject and the file deleted.
• Missing Django classifiers. The standard declares Framework :: Django, Framework :: Django :: 4.2, Framework :: Django :: 5.2; PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 has no framework classifiers despite testing both versions.
• Build-system pins. Standard: setuptools-scm>=8.0; PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 leaves setuptools-scm unpinned.
• Dependencies layout divergence (flag, not necessarily pending). Standard uses [project.optional-dependencies] (dev/test/docs extras); PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 uses PEP 735 [dependency-groups]. Since PR 38's tox.ini will adopt the xblocks-core pattern (which drives envs via dependency_groups), it's actually xblocks-extra that will likely need to converge here — worth deciding explicitly which layout is the standard.
• [tool.semantic_release] build commands differ: standard uses pip install build && … python -m build, PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 uses uv build. PR Modernize Python repo: pyproject.toml + uv + semantic-release #251's is arguably better; just align the two repos on one.

2. MANIFEST.in

• CHANGELOG.rst must go. PR 50 deletes CHANGELOG.rst (semantic-release with changelog: "false" → GitHub Releases are the changelog). PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 still ships CHANGELOG.rst in the repo and include CHANGELOG.rst in MANIFEST.in — both should be removed.
• Philosophy differs. The standard is exclusion-based (prune .github/docs/tests, exclude dev files) with package data declared in pyproject's [tool.setuptools.package-data]. PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 is inclusion-based (recursive-include per file extension) with manual deep-path prunes. Aligning means moving the asset globs into [tool.setuptools.package-data] and slimming MANIFEST.in down to exclusions.
• include LICENSE.txt is redundant — already covered by license-files in pyproject.

3. tox.ini

• ✅ Nothing pending. PR Modernize Python repo: pyproject.toml + uv + semantic-release #251's tox.ini is the pattern PR 38 follows (tox-uv, uv-venv-lock-runner, py312-django{42,52}, quality, docs, translations envs).

4. release.yml

• Actions not SHA-pinned. The standard pins every action to a full commit SHA with a version comment (actions/checkout@de0fac2e… # v6.0.2, python-semantic-release@350c48f… # v10.5.3). PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 uses mutable tags (@v6, @v10.5.3, @v4).
• Artifact actions are old. Standard uses upload-artifact v7.0.1 / download-artifact v8.0.1; PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 uses v4 for both.
• PyPI publish mechanism differs. Standard passes user: __token__ / password: ${{ secrets.PYPI_UPLOAD_TOKEN }}; PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 uses OIDC trusted publishing (no token). OIDC is the more modern approach — decide which one is the org standard, but today they don't match.
• PR Modernize Python repo: pyproject.toml + uv + semantic-release #251's extra Node.js / npm run build step in the release job is repo-specific (JS assets) and fine to keep.

5. CI workflow

• File name: standard is ci.yml; PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 keeps python-tests.yml (referenced by release.yml's run_tests job vs the standard's run_ci). Cosmetic but worth aligning since release.yml uses: it.
• No push-to-main trigger. Standard CI runs on push: branches: [main] + pull_request + workflow_call; PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 only has pull_request + workflow_call (main is covered indirectly via release.yml only).
• tox in CI vs direct uv. The standard runs CI natively with uv (uv sync + make lint / make test-with-coverage), with tox reserved for local dev (PR 38's title says exactly that). PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 drives the whole CI matrix through tox. This is a real philosophical divergence to resolve.
• Setup steps: standard uses setup-uv alone with enable-cache: true and python-version; PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 uses separate setup-python + uncached setup-uv (and setup-uv@v6 is tag-pinned while its neighbors are SHA-pinned — inconsistent).
• Matrix knobs: standard sets fail-fast: false and codecov fail_ci_if_error: false; PR Modernize Python repo: pyproject.toml + uv + semantic-release #251 has true for both.

6. Makefile

• Missing targets vs the standard: lint, format (ruff-based), test, test-with-coverage, docs, clean. PR Modernize Python repo: pyproject.toml + uv + semantic-release #251's Makefile is almost entirely translations plumbing plus upgrade/requirements/selfcheck. The CI standard depends on make lint and make test-with-coverage existing.
• PR Modernize Python repo: pyproject.toml + uv + semantic-release #251's extras are fine to keep: .DEFAULT_GOAL := help (the standard actually lacks this), the edx_lint write_uv_constraints step in upgrade, and the fuller translation suite (validate_translations is even required by its tox.ini).

Repo-level stragglers in PR #251

• Delete CHANGELOG.rst, .coveragerc, and (after ruff migration) pylintrc / pylintrc_tweaks.
• Standard repo has a .python-version file; xblocks-core has none.

---

Top 3 by impact:

1. ruff migration replacing the pylint/pycodestyle/pydocstyle/isort stack
2. CHANGELOG.rst removal to match the semantic-release flow
3. Deciding tox-in-CI vs direct-uv-in-CI — that one goes the other direction and may mean updating the xblocks-extra standard instead

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Modernizes the repo’s Python packaging/tooling by moving metadata/config into pyproject.toml, switching dependency management to uv, and introducing automated releases via python-semantic-release (plus commit message linting).

Changes:

• Migrate packaging metadata/config from setup.py/setup.cfg into pyproject.toml (PEP 621) with setuptools-scm.
• Replace pip-tools/requirements/*.txt with uv dependency groups + updated tox.ini and Make targets.
• Add GitHub Actions workflows for semantic-release publishing and commitlint; update Python CI to use uv.

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pyproject.toml	New canonical packaging + tool configuration; defines dependency groups for uv/tox.
tox.ini	Switch tox to tox-uv with uv-venv-lock-runner and dependency groups.
Makefile	Replace pip-tools workflow with uv-based install/upgrade and new lint/test/docs targets.
README.rst	Update documentation for uv-based setup and adjust project status wording.
.github/workflows/python-tests.yml	Update CI to install dependencies with uv and run tox via uv run.
.github/workflows/release.yml	Add semantic-release-based GitHub Release + PyPI publish via OIDC.
.github/workflows/commitlint.yml	Add Conventional Commits enforcement via reusable workflow.
MANIFEST.in	Adjust packaged root files after metadata migration/removals.
setup.py	Removed legacy setuptools metadata and pip-tools requirement loading.
setup.cfg	Removed legacy tool configuration (isort/wheel).
requirements/*	Removed pip-tools compiled requirements and constraints files in favor of uv.
pylintrc / pylintrc_tweaks	Removed pylint configuration (quality now via ruff).
.github/workflows/pypi-publish.yml	Removed legacy PyPI publish workflow (superseded by release workflow).
.coveragerc	Removed in favor of coverage config in pyproject.toml.
CHANGELOG.rst	Removed legacy changelog file (semantic-release configured without changelog generation).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[farhan]

small fixes to fully align with the xblocks-extra standard.

[farhan]

Thanks @salman2013 — the big items from the last round are all done. One small thing remains:

CI — redundant setup-python step

astral-sh/setup-uv handles Python installation on its own when you pass python-version. The separate actions/setup-python step is redundant and inconsistent with the xblocks-extra standard.

# Remove this:
- name: Set up Python ${{ matrix.python-version }}
  uses: actions/setup-python@a309ff8b... # v6.2.0
  with:
    python-version: ${{ matrix.python-version }}

# Keep only this, with the two extra params:
- name: Install uv
  uses: astral-sh/setup-uv@08807647... # v8.1.0
  with:
    enable-cache: true
    python-version: "${{ matrix.python-version }}"

---

Everything else looks good — ruff, coverage in pyproject, classifiers, SHA-pinning, fail-fast: false, matrix job name, secrets: inherit, and the Makefile targets all match the xblocks-extra standard now.

Change request proposed in assistance with Claude Code

[farhan]

Important

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

Test Results: Modernize Python repo

Tested locally on salman/modernize-branch using the modernize-python-repos skill.

---

❌ Failures (must fix before merging)

1 — Hardcoded __version__ in package source

xblocks_contrib/__init__.py:12 still has __version__ = "0.17.0". With setuptools-scm deriving the version from git tags, this will be permanently stale after any new tag. Remove it (and update docs/conf.py which reads it via regex). If the version is needed at runtime, replace with importlib.metadata.

2 — Invented fail_under coverage threshold

The original .coveragerc had no fail_under — only a [run] section. The PR adds fail_under = 70 in [tool.coverage.report]. The migration rule is: if no threshold existed before, omit it entirely — do not invent one. Remove this line.

---

⚠️ Warnings

1 — Test files in the wheel (129 files)

The PR wheel contains test files (e.g. xblocks_contrib/annotatable/tests/test_annotatable.py) not present in the main branch wheel. Root cause: prune */tests in MANIFEST.in only prunes one directory level deep, and the isolated build with setuptools-scm discovers all git-tracked files. Recommend adding:

[tool.setuptools.exclude_package_data]
"*" = ["tests*", "*.tests*", "spec*", "*.spec*"]

---

[salman2013]

@farhan Could you please take a look at PR again.

[farhan]

Ran full local verification (quality + docs + django42 + django52 — 841 tests pass on both Django versions). One blocker to address before merge, see inline.

[farhan]

LGTM!

Some manual testing of blocks before merging will be great.