Workflow¶

Development environment¶

uv is a required package to develop.

$ git clone https://github.com/vcs-python/libvcs.git

$ cd libvcs

$ uv install -E "docs test coverage lint"

Justfile commands prefixed with watch- will watch files and rerun.

Tests¶

$ uv run py.test

Helpers: just test Rerun tests on file change: just watch-test (requires entr(1))

Documentation¶

Default preview server: http://localhost:8068

sphinx-autobuild will automatically build the docs, watch for file changes and launch a server.

From home directory: just start-docs From inside docs/: just start

Manual documentation (the hard way)¶

cd docs/ and just html to build. just serve to start http server.

Helpers: just build-docs, just serve-docs

Rebuild docs on file change: just watch-docs (requires entr(1))

Rebuild docs and run server via one terminal: just dev-docs

Formatting / linting¶

ruff¶

The project uses ruff to handle formatting, sorting imports and linting.

uv:

$ uv run ruff

If you setup manually:

$ ruff check .

$ just ruff

$ just watch-ruff

requires entr(1).

uv:

$ uv run ruff check . --fix

If you setup manually:

$ ruff check . --fix

ruff format¶

ruff format is used for formatting.

uv:

$ uv run ruff format .

If you setup manually:

$ ruff format .

$ just ruff-format

mypy¶

mypy is used for static type checking.

uv:

$ uv run mypy .

If you setup manually:

$ mypy .

$ just mypy

$ just watch-mypy

requires entr(1).

Releasing¶

Since this software is used in production projects, we don’t want to release breaking changes.

Choose what the next version is. Assuming it’s version 0.9.0, it could be:

  • 0.9.0post0: postrelease, if there was a packaging issue

  • 0.9.1: bugfix / security / tweak

  • 0.10.0: breaking changes, new features

Let’s assume we pick 0.9.1

CHANGES: Assure any PRs merged since last release are mentioned. Give a thank you to the contributor. Set the header with the new version and the date. Leave the “current” header and Insert changes/features/fixes for next release here at the top::

current
-------
- *Insert changes/features/fixes for next release here*

libvcs 0.9.1 (2020-10-12)
-------------------------
- :issue:`1`: Fix bug

libvcs/__init__.py and __about__.py - Set version

$ git commit -m 'Tag v0.9.1'

$ git tag v0.9.1

After git push and git push --tags, CI will automatically build and deploy to PyPI.

Releasing (manual)¶

As of 0.10, uv handles virtualenv creation, package requirements, versioning, building, and publishing. Therefore there is no setup.py or requirements files.

Update __version__ in __about__.py and pyproject.toml::

git commit -m 'build(libvcs): Tag v0.1.1'
git tag v0.1.1
git push
git push --tags
uv build
uv publish