Skip to content

development.rst

Latest commit

 

History

History
72 lines (57 loc) · 3.27 KB

development.rst

File metadata and controls

72 lines (57 loc) · 3.27 KB
Raw

Development, CI and releases

Local checks

From a clean checkout and an activated Python environment:

python3 -m pip install -e . -r requirements-dev.txt
python3 -m pytest -q
python3 -m build
python3 -m twine check --strict dist/*
python3 -m sphinx -W --keep-going -b html docs docs/_build/html

Open docs/_build/html/index.html to read the built guide. Documentation warnings fail CI. Sphinx uses the built-in Alabaster theme; no legacy Flask theme installation is needed. tox optionally runs tests across locally installed Python 3.10–3.14 interpreters.

Repository conventions

Read the root AGENTS.md before changes. Reproduce bugs, add focused tests, and make minimal fixes. Parser tests should use packed binary records and valid CRCs when applicable. Document conversions at the conversion line and check live/archive consistency. Tests must not connect to physical hardware. Update this guide and README when public behavior or workflows change.

CI workflow

.github/workflows/ci.yml runs on pushes to main, pull requests, manual dispatches, and calls from the release workflow. Linux jobs run the full test suite and CLI/import smoke checks on Python 3.10–3.14. A Python 3.12 job builds a wheel and source distribution, validates metadata, builds HTML with warnings as errors, runs tests from the extracted source package, and checks the installed wheel outside the checkout.

Successful build jobs upload distributions and documentation artifacts to the Actions run. All CI jobs use read-only repository permissions. The matrix requires no station, broker, or repository secrets. Maintainers can require these checks through GitHub branch protection.

Release delivery

.github/workflows/release.yml runs when a GitHub Release is published, including prereleases. It calls the full CI workflow on the release tag and, only after successful validation, attaches the wheel, source distribution, and documentation.zip. Only the upload job has contents: write. It uses the built-in GITHUB_TOKEN; no personal access token is needed.

Maintainer procedure:

  1. Update VERSION in pyvantagepro/__init__.py and CHANGES.rst. Package metadata currently removes a trailing dev from that constant; use an explicit final version for a stable release.
  2. Run the local checks and merge the version change into main.
  3. Create a matching version tag, for example v0.4.0, at that commit.
  4. Publish a GitHub Release for that tag with release notes, marking it as a prerelease when appropriate.
  5. Check the Release Actions run and download/install its attached wheel.

The workflow uploads assets after publication, so it requires releases that allow asset additions. If immutable releases are enabled, adapt delivery to upload assets to a draft before publishing. Existing asset names are not overwritten: after a partial upload, remove conflicting assets before rerunning. A failed validation leaves the release without new assets.

This delivery pipeline does not publish to PyPI or deploy GitHub Pages. Read HTML documentation from the CI artifact or release ZIP. PyPI publishing would require configuring a project owner and a trusted publishing workflow.