Contributing to coderpad-py¶

Contributions to this repository must pass tests and linting.

CI is the canonical source of truth.

Install contribution dependencies¶

Initialize the pinned shared specification before running tests:

$ git submodule update --init spec

Repeat this after pulling changes to the specification pin. See OpenAPI Spec for its ownership and update process.

Install Python dependencies in a virtual environment.

$ pip install --editable . --group dev

Spell checking requires enchant. This can be installed on macOS, for example, with Homebrew:

$ brew install enchant

and on Ubuntu with apt:

$ apt-get install -y enchant

Install prek hooks:

$ prek install

Linting¶

Run lint tools either by committing, or with:

$ prek run --all-files --hook-stage pre-commit --verbose
$ prek run --all-files --hook-stage pre-push --verbose
$ prek run --all-files --hook-stage manual --verbose

Running tests¶

Run pytest:

$ pytest

Documentation¶

Documentation is built on Read the Docs.

Run the following commands to build and view documentation locally:

$ uv run --group=dev sphinx-build -M html docs/source docs/build -W
$ python -c 'import os, webbrowser; webbrowser.open("file://" + os.path.abspath("docs/build/html/index.html"))'

Undocumented API variants¶

CoderPad responses sometimes include fields that are missing from the published OpenAPI specification. When you extend the client to support a new empirically observed variant, update all of the following:

Add a newsfragments/<issue>.change.md entry describing the user-visible behavior (see Release Process).
Extend the bullet list in OpenAPI Spec under empirically observed response fields.
Add or extend synthetic fixtures and tests so the variant is covered without storing account-specific payloads in the repository.
Propose contract changes in adamtheturtle/coderpad-openapi, then update the reviewed specification pin here.

Continuous integration¶

Tests are run on GitHub Actions. The configuration for this is in .github/workflows/.

Performing a release¶

See Release Process.

Release notes¶

Write user-facing changes as Markdown in newsfragments/<issue>.change.md. Towncrier writes one Markdown file per version, used directly for GitHub release notes. Invalid fragment names fail release assembly.