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 format"

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#

The project uses black and isort (one after the other). Configurations are in pyproject.toml and setup.cfg:

make black isort: Run black first, then isort to handle import nuances

Linting#

flake8 and mypy run via CI in our GitHub Actions. See the configuration in pyproject.toml and setup.cfg.

flake8#

flake8 provides fast, reliable, barebones styling and linting.

Command

poetry:

$ poetry run flake8

If you setup manually:

$ flake8

make

$ make flake8

Watch

$ make watch_flake8

requires entr(1).

Configuration

See [flake8] in setup.cfg.

[flake8]
exclude = .*/,.tox,*.egg,libvcs/__*__.py,
select = E,W,F,N
max-line-length = 88
# Stuff we ignore thanks to black: https://github.com/ambv/black/issues/429
ignore = E203,W503

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#

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