Skip to content

Modernize Python tooling (pyproject.toml, uv, python-semantic-release) - #328

Open
salman2013 wants to merge 4 commits into
openedx:masterfrom
salman2013:modernize-python-tooling
Open

salman2013 wants to merge 4 commits into
openedx:masterfrom
salman2013:modernize-python-tooling

Conversation

@salman2013

@salman2013 salman2013 commented Nov 10, 2026 •

Copy link
Copy Markdown

Description

Migrates cc2olx from setup.py/pip-tools to pyproject.toml, uv, and python-semantic-release, following openedx/sample-plugin. The package was already in src/ layout, so no code moves.

Changes (one commit per step)

1. Metadata → pyproject.toml (PEP 621)

  • Replaced setup.py, setup.cfg and .coveragerc with pyproject.toml.
  • The version comes from git tags via setuptools-scm. __version__ is kept and read through importlib.metadata.
  • license = "AGPL-3.0-only", matching the old "AGPL v3" classifier (no "or later").
  • include-package-data = false, with templates/** listed. Otherwise setuptools-scm would add tools/README.rst to the wheel.
  • MANIFEST.in now has prune test_data. Otherwise setuptools-scm would add the .imscc fixtures to the sdist (309 KB → 10 MB).
  • Fixed the README's :ref: role, which fails twine check on master. PyPI rejects descriptions that don't render.
  • CHANGELOG.rst has a deprecation note; release notes are now on GitHub Releases.

2. pip-tools → uv

  • requirements/ is replaced by PEP 735 dependency groups and uv.lock.
  • uv.lock was seeded from master's requirements/*.txt pins, so no installed versions change. make upgrade takes upgrades from here on.
  • tox uses tox-uv with uv-venv-lock-runner. CI uses setup-uv and --locked.
  • CI job names and the matrix are unchanged, so the check names stay the same.

3. python-semantic-release

  • release.yml is adapted from sample-plugin's and replaces pypi-publish.yml. Merges to master are versioned from conventional commits, released on GitHub with the dists attached, and published to PyPI via trusted publishing (OIDC). PYPI_UPLOAD_TOKEN is no longer used.

Maintainer actions needed before merge

  1. Push a v0.4.0 tag. The existing tags are bare (0.4.0), and PSR uses v{version}. Without the tag, PSR computes 0.1.0 as the next release.
    git tag v0.4.0 0.4.0 && git push origin v0.4.0
    
  2. Configure a pending trusted publisher on PyPI for project cc2olx, repo openedx/cc2olx, workflow release.yml. The package has never been published, because the 0.4.0 pypi-publish.yml run failed.

Ticket: Ticket: openedx/public-engineering#519

🤖 Generated with Claude Code

salman2013 and others added 3 commits November 10, 2026 15:35
Replace setup.py/setup.cfg/.coveragerc with a PEP 621 pyproject.toml,
using setuptools-scm for the version and an SPDX license expression.
The built wheel's file list matches the one built from setup.py.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Move requirements/*.in into PEP 735 dependency groups, lock them in
uv.lock (seeded from the existing requirements/*.txt pins, so no
versions change), and run tox and CI through tox-uv and setup-uv.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Replace the tag-triggered pypi-publish.yml with release.yml, adapted
from openedx/sample-plugin: merges to master are versioned from their
conventional commits, released on GitHub with the dists attached, and
published to PyPI through trusted publishing.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
@openedx-webhooks openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Nov 10, 2026
@openedx-webhooks

Copy link
Copy Markdown

Thanks for the pull request, @salman2013!

This repository is currently unmaintained.

🔘 Find a technical reviewer To get help with finding a technical reviewer, reach out to the community contributions project manager for this PR:
  1. On the right-hand side of the PR, find the Contributions project, click the caret in the top right corner to expand it, and check the "Primary PM" field for the name of your project manager.
  2. Find their GitHub handle here.

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:

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.

@github-project-automation github-project-automation Bot moved this to Needs Triage in Contributions Nov 10, 2026
@salman2013 salman2013 changed the title build: modernize Python tooling (pyproject.toml, uv, python-semantic-release) Modernize Python tooling (pyproject.toml, uv, python-semantic-release) Nov 10, 2026

@farhan farhan left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done with first pass

on:
push:
branches: [master]
# Run manually on an older branch to cut a patch release for that line.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding it seems fine to me.
But have we decided to add it in the PR's. As per current understanding it's only a timely needed feature.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've kept it. It mirrors the current release.yml on openedx/sample-plugin, which added the workflow_dispatch force input, the "fail a manual run that released nothing" check, and the release/* maintenance branch group together. With all three in place, a manual run can cut a patch release from a release branch, and a manual run that releases nothing fails instead of showing green. Happy to drop all three together if we decide it shouldn't be in these PRs yet.

Comment thread MANIFEST.in
recursive-include src/cc2olx/templates *
recursive-include requirements *
recursive-include tests *
prune test_data

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sdist now picks up every tracked file (uv.lock, .github/, Dockerfile, etc.; 309 KB → 366 KB). Exclude them?

MANIFEST.in:6

Suggested change
prune test_data
prune test_data
prune .github
exclude uv.lock Dockerfile .dockerignore .editorconfig .gitignore codecov.yml

Also, openedx.yaml is legacy, can we delete it?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 5bcce58, using your excludes as written. The sdist is back to 310 KB. Compared with master's sdist, the only files that dropped out are setup.py and requirements/, both deleted on purpose. I've left openedx.yaml alone here because it isn't part of the tooling migration, so it fits better in its own PR.

Comment thread Makefile Outdated
# Let tox control the Django version for tests
sed '/^[dD]jango==/d' requirements/test.txt > requirements/test.tmp
mv requirements/test.tmp requirements/test.txt
pip install .

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uv venvs have no pip, so this uses whatever pip is on PATH (or fails).

Makefile:80

Suggested change
pip install .
uv pip install .

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 5bcce58.

Comment thread pyproject.toml
[tool.setuptools_scm]
version_scheme = "only-version"
local_scheme = "no-local-version"
fallback_version = "0.0.0"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docker builds now report 0.0.0 (.git is in .dockerignore, so setuptools-scm falls back). Master's image reported 0.4.0.

Dockerfile:2

ARG VERSION=0.0.0
ENV SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CC2OLX=$VERSION

docker build --build-arg VERSION=0.4.0 -t cc2olx .

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 5bcce58. I also updated the README's docker build example to pass --build-arg VERSION=<VERSION>. Checked locally: with VERSION=0.4.0 the image's cc2olx.__version__ is 0.4.0, and without the build arg it's 0.0.0.

Comment thread .github/workflows/ci.yml
pull_request:
branches:
- '**'
workflow_call:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With workflow_call from release.yml, the push: trigger makes CI run twice on every merge. Same fix as openedx/forum#293:

.github/workflows/ci.yml:3

on:
  pull_request:
    branches:
      - '**'
  workflow_call:

and point the badge at release.yml:

README.rst:4

.. image:: https://github.com/openedx/cc2olx/actions/workflows/release.yml/badge.svg?branch=master
    :target: https://github.com/openedx/cc2olx/actions/workflows/release.yml

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 5bcce58: dropped push: and pointed the badge at release.yml. The live sample-plugin ci.yml also has only pull_request and workflow_call now.

Comment thread Makefile Outdated
requirements: ## install development environment requirements
pip install -qr requirements/pip-tools.txt
pip-sync requirements/dev.txt requirements/private.*
uv sync --group dev

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: fail instead of silently rewriting uv.lock.

Makefile:87

Suggested change
uv sync --group dev
uv sync --locked --group dev

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 5bcce58.

Comment thread pyproject.toml
name = "cc2olx"
dynamic = ["version"]
description = "Command line tool, that converts Common Cartridge courses to Open edX Studio imports."
readme = "README.rst"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: other modernized openedx repos set this.

pyproject.toml:9

Suggested change
readme = "README.rst"
readme = "README.rst"
authors = [
{name = "Open edX Project", email = "[email protected]"},
]

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 5bcce58.

Comment thread tox.ini Outdated
Comment on lines 5 to 7
[pytest]
DJANGO_SETTINGS_MODULE = test_settings
norecursedirs = .* requirements

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: dead config, pytest.ini wins (WARNING: ignoring pytest config in tox.ini!), and requirements no longer exists.

tox.ini:5-7

Suggested change
[pytest]
DJANGO_SETTINGS_MODULE = test_settings
norecursedirs = .* requirements

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed in 5bcce58. Tests still collect and pass, 169 as before.

- Run CI only on pull requests and from release.yml, so a merge to
  master doesn't run it twice; point the README badge at release.yml.
- Exclude repo-only files from the sdist.
- Let the Docker build pass the version to setuptools-scm.
- Use uv pip and uv sync --locked in the Makefile.
- Set authors and drop the dead [pytest] section from tox.ini.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
@salman2013
salman2013 requested a review from farhan November 11, 2026 10:59
@mphilbrick211 mphilbrick211 moved this from Needs Triage to In Eng Review in Contributions Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core contributor PR author is a Core Contributor (who may or may not have write access to this repo). open-source-contribution PR author is not from Axim or 2U

Projects

Status: In Eng Review

Development

Successfully merging this pull request may close these issues.

3 participants