Workflow

Development environment

poetry is a required package to develop.

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

$ cd libvcs

$ poetry install -E "docs test coverage lint"

Makefile commands prefixed with watch_ will watch files and rerun.

Tests

$ poetry run py.test

Helpers: make test Rerun tests on file change: make 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: make start_docs From inside docs/: make start

Manual documentation (the hard way)

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

Helpers: make build_docs, make serve_docs

Rebuild docs on file change: make watch_docs (requires entr(1))

Rebuild docs and run server via one terminal: make dev_docs (requires above, and a make(1) with -J support, e.g. GNU Make)

Formatting / linting

black

black is used for formatting.

Command

poetry:

$ poetry run black .

If you setup manually:

$ black .

make

$ make black

In the future, ruff (below) may replace black as formatter.

ruff

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

Command

poetry:

$ poetry run ruff

If you setup manually:

$ ruff .

make

$ make ruff

Watch

$ make watch_ruff

requires entr(1).

Fix files

poetry:

$ poetry run ruff . --fix

If you setup manually:

$ ruff . --fix

mypy

mypy is used for static type checking.

Command

poetry:

$ poetry run mypy .

If you setup manually:

$ mypy .

make

$ make mypy

Watch

$ make watch_mypy

requires entr(1).

mypy

mypy is used for static type checking.

Command

poetry:

$ poetry run mypy .

If you setup manually:

$ mypy .

make

$ make mypy

Watch

$ make watch_mypy

requires entr(1).

Releasing

Since this software 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, poetry 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
poetry build
poetry publish