Development and releases#

Setting up#

git clone https://github.com/directelectron/de-twin
cd de-twin
uv sync --group dev          # the package (editable), deapi, pytest, towncrier, ruff
uv run pytest                # ~340 tests, a few minutes

On Windows, cpp\build.bat builds the stand-alone check of DE-Server’s ExternalFrameSource (needs Visual Studio); the layout and C++ ↔ Python interop tests run when it has been built and are skipped otherwise.

Build the documentation with:

uv sync --extra docs
uv run sphinx-build -b html docs docs/_build/html -W --keep-going

Changelog entries#

Every pull request that changes something a user would notice adds a news fragment to upcoming_changes/, named {PR number}.{type}.rst (types: api_change, new_feature, bugfix, deprecation, removal, doc, maintenance). See upcoming_changes/README.rst. Preview the next release notes with:

uvx towncrier build --draft --version NEXT

Making a release#

Releases are prepared by a workflow and published by hand on GitHub.

  1. Prepare. In GitHub, Actions → Prepare Release → Run workflow. Pick the bump (minor, bugfix, major; pre-release / beta for betas, finalize to turn a beta into the stable release). The workflow bumps the version in pyproject.toml, builds CHANGELOG.rst from the fragments (and deletes them), adds the version to the docs switcher, and opens a release/vX.Y.Z pull request.

  2. Review and merge that pull request once CI passes. Edit CHANGELOG.rst in the PR if the notes need work.

  3. Publish on GitHub. Releases → Draft a new release: tag vX.Y.Z on main (the tag must match pyproject.toml), title vX.Y.Z, paste the version’s CHANGELOG.rst section as the notes, tick pre-release for a beta, and Publish release.

  4. Publishing runs the Release workflow: it checks the tag matches the package version, builds the wheel and sdist, uploads them to PyPI by trusted publishing, and attaches them to the GitHub Release. Pushing the tag also builds that version’s documentation.

One-time setup#

  • PyPI: on pypi.org, Your projects → Publishing → Add a pending publisher: project de-twin, owner directelectron, repository de-twin, workflow release.yml, environment pypi.

  • GitHub: create an environment named pypi (Settings → Environments); optionally require a reviewer for it. Enable GitHub Pages from the gh-pages branch once the Docs workflow has pushed it.