Skip to content

Development

Setup

git clone https://github.com/julianschelb/retexo.git
cd retexo
pip install -e ".[dev,lexical]"
pre-commit install

Tasks

poe test          # pytest
poe test-cov      # pytest with coverage
poe lint          # ruff
poe docs          # serve the docs at http://127.0.0.1:8000
poe docs-build    # build the docs to site/
poe webapp        # run the review app in development mode

Tests

pytest runs the whole suite. A test that needs something a plain install does not bring is skipped with its reason: the lexical extra (CLTK), a spaCy English model, or the word-level annotation files, which are not part of this repository. tests/conftest.py lists what each skipped test needs.

Some older test modules are scripts: they run their checks at import time and exit with a status. conftest.py keeps pytest from importing them and tests/test_script_style.py runs each as a subprocess instead.

Scope

Retexo is the package: the model, the generator, the active-learning loop, the baselines and the scorer. The experiments that use it, with their sweeps and run folders, live in the experiment repository, which installs retexo like any other dependency.

Documentation

The docs are built with MkDocs, the Material theme and mkdocstrings, from docs/ and the docstrings (Google style). The review app in webapp/ is built separately and published under /demo/ next to them.

Commits

Commit messages follow Conventional Commits.

Releasing

Releases are manual and published to PyPI by GitHub Actions through trusted publishing, so no token is stored.

  1. Set the new version in pyproject.toml and in src/retexo/__init__.py (a test checks that they agree) and add a section for it to CHANGELOG.md.
  2. Merge to main once CI is green.
  3. Create a GitHub release with the tag v<version>. The Publish to PyPI workflow builds the sdist and wheel, installs the wheel into a clean environment to check that it imports, and uploads it.

To try a build first, run the workflow by hand and choose testpypi; a manual run cannot reach the real index.

Who can publish: only a release can upload to PyPI, and only the repository owner can create one. The pypi environment accepts v* tags only and waits for the owner's approval; the tags v* are protected by a ruleset. On PyPI the upload is tied to this repository, workflow and environment, and the project has no API tokens.

One-time setup: add retexo as a pending trusted publisher on pypi.org (and on test.pypi.org), with the owner julianschelb, the repository retexo, the workflow publish.yml and the environment pypi (testpypi for the test index), and create the same environments under Settings, Environments in the GitHub repository.