Releasing OntoSQL

Checklist for publishing a new version.

Pre-release

1. Ensure version in pyproject.toml matches the release tag.
2. Update CHANGELOG.md (move items from [Unreleased] to a new version section).
3. Confirm README, SPECS.md, ARCHITECTURE.md, ECOSYSTEM.md, and CHANGELOG are aligned with the release scope.
4. Run the full CI suite locally:

pip install -e ".[dev]"
ruff check src tests
ruff format --check src tests
ty check
pytest --cov=ontosql --cov-fail-under=90
mkdocs build --strict

1. Build and smoke-test the wheel:

pip install build
python -m build
pip install dist/ontosql-*.whl
python -c "import ontosql; print(ontosql.__version__)"

GitHub release

git tag -a vX.Y.Z -m "Release X.Y.Z"
git push origin vX.Y.Z

Create a GitHub release from the tag and paste the relevant CHANGELOG.md section.

Pushing a semver tag (v*.*.*) triggers the Release workflow, which runs pre-release checks before publishing:

Check	Purpose
Tag ↔ pyproject.toml version	Prevents mismatched releases
CHANGELOG.md section	Ensures release notes exist for the tag
Ruff lint + format	Code style
ty check	Static types
Pytest (≥90% coverage)	Test suite
mkdocs build --strict	Documentation
Postgres integration tests	Dialect smoke tests
twine check + wheel import	Distribution metadata and installability

Publish to PyPI runs only when all checks pass.

PyPI

The PyPI distribution name is ontosql.

Automated publish (recommended)

1. Create a PyPI API token at pypi.org/manage/account/token/ scoped to the ontosql project (or the whole account for the first upload).
2. Add it as a GitHub repository secret named PYPI_API_TOKEN (Settings → Secrets and variables → Actions).
3. Tag and push — the Release workflow runs on tags matching v*.*.*:

git tag -a vX.Y.Z -m "Release X.Y.Z"
git push origin vX.Y.Z

Manual publish

python -m build
pip install twine
twine check dist/*
twine upload dist/*

Requires PyPI credentials configured (~/.pypirc or TWINE_USERNAME=__token__ / TWINE_PASSWORD).

PyPI description and readme come from pyproject.toml — update them in the same release PR as README.md.

Documentation hosting

Docs are built with MkDocs (mkdocs build --strict) from mkdocs.yml.

Host	Role	Trigger
Read the Docs	Canonical public documentation	RTD webhook on push/tags — .readthedocs.yaml
GitHub Pages	Optional mirror	Push to main — pages workflow

Use Read the Docs URLs in README, PyPI Documentation field, and external links. GitHub Pages is a convenience mirror only.

One-time RTD setup: create a project named ontosql, point at this repository, enable builds for main and tags. .readthedocs.yaml installs pip install ".[docs]" and runs MkDocs with fail_on_warning: true.