1# Development
2
3[poetry] is a required package to develop.
4
5`git clone https://github.com/tmux-python/libtmux.git`
6
7`cd libtmux`
8
9`poetry install -E "docs test coverage lint format"`
10
11Makefile commands prefixed with `watch_` will watch files and rerun.
12
13## Tests
14
15`poetry run py.test`
16
17Helpers: `make test`
18Rerun tests on file change: `make watch_test` (requires [entr(1)])
19
20## Documentation
21
22Default preview server: http://localhost:8023
23
24`cd docs/` and `make html` to build. `make serve` to start http server.
25
26Helpers:
27`make build_docs`, `make serve_docs`
28
29Rebuild docs on file change: `make watch_docs` (requires [entr(1)])
30
31Rebuild docs and run server via one terminal: `make dev_docs` (requires above, and a
32`make(1)` with `-J` support, e.g. GNU Make)
33
34## Formatting / Linting
35
36The project uses [black] and [isort] (one after the other) and runs [flake8] via
37CI. See the configuration in `pyproject.toml` and `setup.cfg`:
38
39`make black isort`: Run `black` first, then `isort` to handle import nuances
40`make flake8`, to watch (requires `entr(1)`): `make watch_flake8`
41
42## Releasing
43
44Since this software is used by tens of thousands of users daily, we don't want
45to release breaking changes. Additionally this is packaged on large Linux/BSD
46distros, so we must be mindful of architectural changes.
47
48Choose what the next version is. Assuming it's version 0.9.0, it could be:
49
50- 0.9.0post0: postrelease, if there was a packaging issue
51- 0.9.1: bugfix / security / tweak
52- 0.10.0: breaking changes, new features
53
54Let's assume we pick 0.9.1
55
56`CHANGES`: Assure any PRs merged since last release are mentioned. Give a
57thank you to the contributor. Set the header with the new version and the date.
58Leave the "current" header and _Insert changes/features/fixes for next release here_ at
59the top::
60
61    current
62    -------
63    - *Insert changes/features/fixes for next release here*
64
65    libtmux 0.9.1 (2020-10-12)
66    --------------------------
67    - :issue:`1`: Fix bug
68
69`libtmux/__init__.py` and `__about__.py` - Set version
70
71`git commit -m 'Tag v0.9.1'`
72
73`git tag v0.9.1`
74
75`pip install wheel twine`
76
77`python setup.py sdist bdist_wheel`
78
79`twine upload dist/*`
80
81### Twine
82
83`twine upload dist/*`
84
85You will be asked for PyPI login information.
86
87### Releasing with Poetry (hypothetical)
88
89This isn't used yet since package maintainers may want setup.py in the source.
90See https://github.com/tmux-python/tmuxp/issues/625.
91
92As of 0.10, [poetry] handles virtualenv creation, package requirements, versioning,
93building, and publishing. Therefore there is no setup.py or requirements files.
94
95Update `__version__` in `__about__.py` and `pyproject.toml`::
96
97    git commit -m 'build(libtmux): Tag v0.1.1'
98    git tag v0.1.1
99    git push
100    git push --tags
101    poetry build
102    poetry deploy
103
104[twine]: https://twine.readthedocs.io/
105[poetry]: https://python-poetry.org/
106[entr(1)]: http://eradman.com/entrproject/
107[black]: https://github.com/psf/black
108[isort]: https://pypi.org/project/isort/
109[flake8]: https://flake8.pycqa.org/
110