1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
# Environment setup
You need Python installed.
It is recommended to install the same Python version that is packaged in the official installer files.
You can look up this version in the file `.github/workflows/ci/workflow_context.yml` in the vars section (`default_python`).
Tox simplifies the process of creating and managing isolated virtual environments,
handling dependency installation, and running the test suite in isolation. This
ensures a clean and consistent testing environment.
However, it is still recommended to install and run tox within a Python virtual
environment created using tools like [venv](https://docs.python.org/3/library/venv.html).
This helps keep your global Python environment clean, avoids project conflicts, and
isolates tox and its dependencies.
A typical setup looks like this:
### Linux/macOS (Bash):
```bash
cd path/to/plover
python -m venv .venv
source .venv/bin/activate
pip install -r reqs/dev.txt
pre-commit install
pre-commit run --all-files
tox
```
### Windows (PowerShell):
```powershell
cd path\to\plover
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r reqs\dev.txt
pre-commit install
pre-commit run --all-files
tox
```
Some features require a Bash shell, so on Windows you may need to use Git Bash or WSL instead of PowerShell.
## Tox
The command for using tox is: `tox {-e envlist} {-- arguments}`. Use `tox -a
-v` to get a list of available environments.
The same virtual environment is reused by the following tox environments:
- `tox -e test -- ARGS`: run the testsuite. This is the default environment
when not provided.
Example: `tox -e test -- test/gui_qt`
- `tox -e launch -- ARGS`: run Plover from source.
Example: `tox -e launch -- -l debug`
- `tox -e setup -- COMMAND`: run `./setup.py COMMAND` to create a binary
distribution. See also section below.
Example: `tox -e setup -- bdist_appimage`
- `tox -e packaging_checks`: run the same packaging checks as the CI (add `--
-n` to see a dry-run of the exact checks).
- `tox -e plugins_install -- ARGS`: install the plugins specified in `ARGS`, where
plugins are separated by space. You can also specify plugin versions. Note that
this process uses pip directly for installation, not the plugins manager.
Example: `tox -e plugins_install -- some_plugin==1.0.0 another_plugin`
- `tox -e release_prepare -- NEW_VERSION`: execute all the steps necessary for
preparing a new release: patch the version to `NEW_VERSION` and update
`NEWS.md`, staging all the changes for review.
- `tox -e release_finalize`: finalize the release: commit the staged changes,
create an annotated tag, and print the git command necessary for pushing the
release to GitHub.
The virtual environment created by tox lives in `.tox/dev`, and can be [activated like
any other virtual environment](https://virtualenv.pypa.io/en/latest/user_guide.html#activators).
The configuration also provides support for lightweight tests only environment:
`pyX`, where `X` is the version of the Python interpreter to use. E.g. running
`tox -e 'py3,py36,py37,py38,py39` will execute the testsuite for each version
of Python we support.
# Creating a binary distribution
A number of commands are provided by `setup.py` for creating binary
distributions (which include all the necessary dependencies):
- `bdist_appimage`: Linux only, create an [AppImage](https://appimage.org/).
- `bdist_app`: macOS only, build an **application bundle**.
- `bdist_dmg`: macOS only, create a **disk image**.
- `bdist_win`: Windows only, create a portable version.
Use `bdist_xxx --help` to get more information on each command supported options.
# Making a pull request
When making a pull request, please include a short summary of the changes
and a reference to any issue tickets that the PR is intended to solve.
All PRs with code changes should include tests. All changes should include a
changelog entry.
Plover uses [towncrier](https://pypi.org/project/towncrier) for changelog
management, so when making a PR, please add a news fragment in the `news.d/`
folder. Changelog files are written in Markdown and should be a 1 or 2 sentence
description of the substantive changes in the PR.
They should be named `<section>/<pr_number>.<category>.md`, where the sections
/ categories are:
- `feature`: New features:
- `core`: Core changes.
- `dict`: Updates to the default dictionaries.
- `ui`: Changes to the user interface.
- `linux`: Linux specific changes.
- `osx`: macOS specific changes.
- `windows`: Windows specific changes.
- `bugfix`: For bugfixes, support the same categories as for `feature`.
- `api`: For documenting changes to the public/plugins API:
- `break`: For breaking (backward incompatible) changes.
- `dnr`: For deprecations of an existing feature or behavior.
- `new`: For other (backward compatible) changes, like new APIs.
A pull request may have more than one of these components, for example a code
change may introduce a new feature that deprecates an old feature, in which
case two fragments should be added. It is not necessary to make a separate
documentation fragment for documentation changes accompanying the relevant
code changes. See the following for an example news fragment:
```bash
$ cat news.d/bugfix/1041.ui.md
Fix possible crash when changing machine parameters in the configuration dialog.
```
|
