Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
161 lines (98 loc) · 4.75 KB

DEVELOPMENT.md

File metadata and controls

161 lines (98 loc) · 4.75 KB
Raw

Development And Publishing

Prerequisites

Environment Setup

This project uses uv to manage dependencies. uv is pretty good at automatically sync-ing. But if you need to explicitly set everything up, try:

just setup

This will create a virtualenv at ./.venv and install dependencies with uv.

Just Tasks

To list all Just recipes, run just --list. Common ones include:

Command Description
just qa Format, type check, test and lint
just setup Set up the environment
just update Update dependencies
just format Format the project
just check Check type annotations with both pyright and mypy
just test Run tests with pytest
just lint Lint the project
just docs Live generate docs and host on a development webserver
just tag Tag the release in git

Note that this list may be out of date. Reference just --list for a fully up-to-date list of recipes.

Updating Modules

To update the modules being used, run:

just update

Interactive Environments

To activate the venv in a subshell:

just shell

To fire up an interactive console:

just console

Note that I haven't figured out how to auto-exec code on load - you'll need to import everything. The easiest thing may be to use full fat Jupyter, potentially with jpterm.

Development Loop

There are four main just tasks:

  • just format - format with black and isort
  • just check - check type annotations with pyright
  • just test - run tests with pytest
  • just lint - lint with flake8 and validate-pyproject

To run all four in a row, simply run just. Then, run individual checks until you're happy with it, and run just again to make sure all is well.

Cross-Version Tests with tox

I usually lean on Github Actions for checking the test matrix, but just tox should run them with tox. An avenue to explore may be acting smarter about installing versions of Python listed in the test matrix.

Generating Docs

Docs for published projects are automatically generated by readthedocs, but you can also preview them locally by running:

just docs

This will use mkdoc's dev server - click the link, good to go. It even supports hot reload!

Updating CONTRIBUTORS.md

Any contributions by new developers must be added to CONTRIBUTORS.md.

The general format is:

{{ contributor_name }} @{{github_handle }} <{{ email_address }}>

Email address may be withheld if there are privacy concerns.

⚠️ On AI Assisted Contributions

If a commit was created with the use of an AI coding assistant, you must:

  • Add a bot emoji (🤖) to the beginning of relevant commit messages
  • Add a bot emoji (🤖) to the beginning of any relevant changelog entries
  • Notify the reviewer that AI tooling was used for relevant PRs

I am not going to demand that developers do not use AI coding assistants. However:

  1. Knowing AI was involved is important for comprehensive code reviews, as AI makes different mistakes than humans
  2. End users have the right to know that AI was used in the creation of their software

Publishing

Do a Final Check

Run just to do final checks.

Update the Changelog

Update the CHANGELOG.md file to detail the changes being rolled into the new version.

Update the Version in pyproject.toml

I do my best to follow semver when updating versions.

Add a Git Tag

I try to use git tags to tag versions - there's a just task:

just tag

Push the Tag to GitHub

git push origin main --tags

Check on GitHub Actions

This should trigger a GitHub Action which publishes to PyPI and creates a GitHub Release. Go to GitHub and make sure it worked.

Check on RTD

RTD should build automatically but I find there's a delay so I like to kick it off manually. Log into RTD, log in, then go to the pyee project page and build latest and stable.

(Optional) Announce on Social Media

It's not official, but I like to announce the release on Bluesky and Mastodon.

(Optional) Build and Publish Manually

If you want to publish the package manually, run:

just publish

This should automatically build the package and upload with uv.