Development#
poetry is a required package to develop.
$ git clone https://github.com/tmux-python/libtmux.git
$ cd libtmux
$ 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))
Pytest plugin#
See also
See tmux pytest plugin.
Documentation#
Default preview server: http://localhost:8023
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
: Runblack
first, thenisort
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.
poetry:
$ poetry run flake8
If you setup manually:
$ flake8
$ make flake8
$ make watch_flake8
requires entr(1)
.
See [flake8]
in setup.cfg.
[flake8]
exclude = .*/,*.egg,src/libtmux/_compat.py,src/libtmux/__*__.py
select = E,W,F,N
max-line-length = 88
# Stuff we ignore thanks to black: https://github.com/ambv/black/issues/429
extend-ignore = E203,W503
mypy#
mypy is used for static type checking.
poetry:
$ poetry run mypy .
If you setup manually:
$ mypy .
$ make mypy
$ make watch_mypy
requires entr(1)
.
Releasing#
Since this software is used by tens of thousands of users daily, we don’t want to release breaking changes. Additionally this is packaged on large Linux/BSD distros, so we must be mindful of architectural 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*
libtmux 0.9.1 (2020-10-12)
--------------------------
- :issue:`1`: Fix bug
libtmux/__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 with Poetry (manual)#
This isn’t used yet since package maintainers may want setup.py in the source. See https://github.com/tmux-python/tmuxp/issues/625.
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(libtmux): Tag v0.1.1'
git tag v0.1.1
git push
git push --tags
poetry build
poetry deploy