| 1 |
############# |
| 2 |
Development |
| 3 |
############# |
| 4 |
|
| 5 |
.. toctree:: |
| 6 |
:hidden: |
| 7 |
|
| 8 |
onboarding |
| 9 |
|
| 10 |
************ |
| 11 |
Key points |
| 12 |
************ |
| 13 |
|
| 14 |
If you're already experienced with submitting GitHub PRs to open-source Python projects, the following are the key |
| 15 |
points you need to know about this project. (If you're not, you should carefully read all the documentation after this |
| 16 |
section. This section contains only highlights; it's not a substitute for reading this entire file.) |
| 17 |
|
| 18 |
- Check the `style guide <#code-style-guide>`_ below. Note that ``tox -e fix`` will not catch the following: |
| 19 |
|
| 20 |
- Lines wrapped at less than 120 characters. Lines should be wrapped at 120 characters, not the PEP-8 standard of 79. |
| 21 |
- Variable names should be at least two characters long. |
| 22 |
|
| 23 |
- Documentation is in `RST <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_ format; beware the |
| 24 |
differences from GitHub Markdown. The tox ``docs`` and ``fix`` targets will catch only some RST errors; documentation |
| 25 |
changes *must* be checked visually (see below). |
| 26 |
- All PRs that make changes visible to an end user require a changelog entry. This should reference an issue if it |
| 27 |
closes that issue, otherwise reference the PR. Create one or more (if there's more than one issue) |
| 28 |
``docs/changelog/####.{breaking,deprecation,feature,bugfix,doc,packaging,contrib,misc}.rst`` per the `changelog entry |
| 29 |
<#changelog-entries>`_ section below. |
| 30 |
- GitHub Actions will do a full set of `tests and checks <#automated-testing>`_ when the PR is submitted. For local |
| 31 |
testing you'll need to install your own "top-level" tox (using pipx_ or similar is fine) and use the following targets |
| 32 |
(tox environments): |
| 33 |
|
| 34 |
- :samp:`tox -e py [-- {pytest-arg ...}]` to `test code changes <#running-tests>`_. This will skip tests for which you |
| 35 |
are missing dependencies, but those tests will still be run by GitHub Actions. |
| 36 |
- ``tox -e type`` to typecheck changes. (All new code should have complete type annotations.) |
| 37 |
- ``tox -e docs`` to build documentation changes and update the changelog, followed by viewing (with a browser) the |
| 38 |
generated HTML files under :file:`.tox/docs_out/html/`. The required changelog entry can be viewed at the "Release |
| 39 |
History" link at the left. |
| 40 |
- ``tox -e fix`` to lint code, documentation and any other changes to the repo. This will also fix the code and write |
| 41 |
out the changed files; you can update your commit with `git commit --amend`. |
| 42 |
|
| 43 |
***************** |
| 44 |
Getting started |
| 45 |
***************** |
| 46 |
|
| 47 |
``tox`` is a volunteer maintained open source project and we welcome contributions of all forms. The sections below will |
| 48 |
help you get started with development, testing, and documentation. We’re pleased that you are interested in working on |
| 49 |
tox. This document is meant to get you setup to work on tox and to act as a guide and reference to the development |
| 50 |
setup. If you face any issues during this process, please :issue:`open an issue |
| 51 |
<new?title=Trouble+with+development+environment>` about it on the issue tracker. |
| 52 |
|
| 53 |
Setup |
| 54 |
===== |
| 55 |
|
| 56 |
tox is a command line application written in Python. To work on it, you'll need: |
| 57 |
|
| 58 |
- **Source code**: available on :gh_repo:`GitHub <tox-dev/tox>`. You can use ``git`` to clone the repository: |
| 59 |
|
| 60 |
.. code-block:: shell |
| 61 |
|
| 62 |
git clone https://github.com/tox-dev/tox |
| 63 |
cd tox |
| 64 |
|
| 65 |
- **Python interpreter**: We recommend using ``CPython``. You can use `this guide |
| 66 |
<https://realpython.com/installing-python/>`_ to set it up. |
| 67 |
- :pypi:`tox`: to automatically get the projects development dependencies and run the test suite. We recommend |
| 68 |
installing it using `pipx <https://pipxproject.github.io/pipx/>`_. |
| 69 |
|
| 70 |
Running from source tree |
| 71 |
======================== |
| 72 |
|
| 73 |
The easiest way to do this is to generate the development tox environment, and then invoke tox from under the |
| 74 |
``.tox/dev`` folder |
| 75 |
|
| 76 |
.. code-block:: shell |
| 77 |
|
| 78 |
tox -e dev |
| 79 |
.tox/dev/bin/tox # on Linux |
| 80 |
.tox/dev/Scripts/tox # on Windows |
| 81 |
|
| 82 |
Running tests |
| 83 |
============= |
| 84 |
|
| 85 |
tox's tests are written using the :pypi:`pytest` test framework. :pypi:`tox` is used to automate the setup and execution |
| 86 |
of tox's tests. |
| 87 |
|
| 88 |
To run tests locally execute: |
| 89 |
|
| 90 |
.. code-block:: shell |
| 91 |
|
| 92 |
tox -e py |
| 93 |
|
| 94 |
This will run the test suite for the same Python version as under which ``tox`` is installed. Alternatively you can |
| 95 |
specify a specific version of Python by using the ``pyNN`` format, such as: ``py38``, ``pypy3``, etc. |
| 96 |
|
| 97 |
``tox`` has been configured to forward any additional arguments it is given to ``pytest``. This enables the use of |
| 98 |
pytest's `rich CLI <https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run>`_. As an example, |
| 99 |
you can select tests using the various ways that pytest provides: |
| 100 |
|
| 101 |
.. code-block:: shell |
| 102 |
|
| 103 |
# Using markers |
| 104 |
tox -e py -- -m "not slow" |
| 105 |
# Using keywords |
| 106 |
tox -e py -- -k "test_extra" |
| 107 |
|
| 108 |
Some tests require additional dependencies to be run, such is the various shell activators (``bash``, ``fish``, |
| 109 |
``powershell``, etc). The tests will be skipped automatically if the dependencies are not present. Please note however |
| 110 |
that in CI all tests are run; so even if all tests succeed locally for you, they may still fail in the CI. |
| 111 |
|
| 112 |
Running linters |
| 113 |
=============== |
| 114 |
|
| 115 |
tox uses :pypi:`pre-commit` for managing linting of the codebase. ``pre-commit`` performs various checks on all files in |
| 116 |
tox and uses tools that help following a consistent code style within the codebase. To use linters locally, run: |
| 117 |
|
| 118 |
.. code-block:: shell |
| 119 |
|
| 120 |
tox -e fix |
| 121 |
|
| 122 |
.. note:: |
| 123 |
|
| 124 |
Avoid using ``# noqa`` comments to suppress linter warnings - wherever possible, warnings should be fixed instead. |
| 125 |
``# noqa`` comments are reserved for rare cases where the recommended style causes severe readability problems or |
| 126 |
sidestep bugs within the linters. |
| 127 |
|
| 128 |
Code style guide |
| 129 |
================ |
| 130 |
|
| 131 |
- First and foremost, the linters configured for the project must pass; this generally means following PEP-8 rules, as |
| 132 |
codified by ``ruff`` (which replaces the previously used ``flake8``, ``black``, ``isort``, and ``pyupgrade``). |
| 133 |
- The supported Python versions (and the code syntax to use) are listed in the ``pyproject.toml`` file in the |
| 134 |
``project/requires-python`` entry. |
| 135 |
- All code (tests too) must be type annotated as much as required by ``mypy``. |
| 136 |
- We use a line length of 120. |
| 137 |
- Exception messages should only be capitalized (and ended with a period/exclamation mark) if they are multi-sentenced, |
| 138 |
which should be avoided. Otherwise, use statements that start with lowercase. |
| 139 |
- All function (including test) names must follow PEP-8, so they must be fully snake cased. All classes are upper |
| 140 |
camel-cased. |
| 141 |
- Prefer f-strings instead of the ``str.format`` method. |
| 142 |
- Tests should contain as little information as possible but do use descriptive variable names within it. |
| 143 |
|
| 144 |
Building documentation |
| 145 |
====================== |
| 146 |
|
| 147 |
tox's documentation is built using :pypi:`Sphinx`. The documentation is written in reStructuredText. To build it |
| 148 |
locally, run: |
| 149 |
|
| 150 |
.. code-block:: shell |
| 151 |
|
| 152 |
tox -e docs |
| 153 |
|
| 154 |
The built documentation can be found in the ``.tox/docs_out/html`` folder and may be viewed by opening ``index.html`` |
| 155 |
within that folder. |
| 156 |
|
| 157 |
************** |
| 158 |
Contributing |
| 159 |
************** |
| 160 |
|
| 161 |
Submitting pull requests |
| 162 |
======================== |
| 163 |
|
| 164 |
Submit pull requests (PRs) against the ``main`` branch, providing a good description of what you're doing and why. You |
| 165 |
must have legal permission to distribute any code you contribute to tox and it must be available under the MIT License. |
| 166 |
Provide tests that cover your changes and run the tests locally first. tox :ref:`supports <compatibility-requirements>` |
| 167 |
multiple Python versions and operating systems. Any pull request must consider and work on all these platforms. |
| 168 |
|
| 169 |
Pull requests should be small to facilitate review. Keep them self-contained, and limited in scope. Studies have shown |
| 170 |
that review quality falls off as patch size grows. In particular, pull requests must not be treated as "feature |
| 171 |
branches", with ongoing development work happening within the PR. Instead, the feature should be broken up into smaller, |
| 172 |
independent parts which can be reviewed and merged individually. |
| 173 |
|
| 174 |
Additionally, avoid including "cosmetic" changes to code that is unrelated to your change, as these make reviewing the |
| 175 |
PR more difficult. Examples include re-flowing text in comments or documentation, or addition or removal of blank lines |
| 176 |
or whitespace within lines. Such changes can be made separately, as a "formatting cleanup" PR, if needed. |
| 177 |
|
| 178 |
Automated testing |
| 179 |
================= |
| 180 |
|
| 181 |
All pull requests and merges to the ``main`` branch are tested using :gh:`GitHub Actions <features/actions>` (configured |
| 182 |
by ``check.yaml`` file inside the ``.github/workflows`` directory). You can find the status and the results to the CI |
| 183 |
runs for your PR on GitHub's Web UI for the pull request. You can also find links to the CI services' pages for the |
| 184 |
specific builds in the form of "Details" links, in case the CI run fails and you wish to view the output. |
| 185 |
|
| 186 |
To trigger CI to run again for a pull request, you can close and open the pull request or submit another change to the |
| 187 |
pull request. If needed, project maintainers can manually trigger a restart of a job/build. |
| 188 |
|
| 189 |
Changelog entries |
| 190 |
================= |
| 191 |
|
| 192 |
The ``changelog.rst`` file is managed using :pypi:`towncrier` and all changes must be accompanied by a changelog entry. |
| 193 |
To add an entry to the changelog, first you need to have created an issue describing the change you want to make. A pull |
| 194 |
request itself *may* function as such, but it is preferred to have a dedicated issue (for example, in case the PR ends |
| 195 |
up rejected due to code quality reasons). |
| 196 |
|
| 197 |
There is no need to create an issue for trivial changes, e.g. for typo fixes. |
| 198 |
|
| 199 |
Once you have an issue or pull request, you take the number and you create a file inside of the ``docs/changelog`` |
| 200 |
directory named after that issue number with an extension of: |
| 201 |
|
| 202 |
- ``breaking.rst`` - backward incompatible changes, |
| 203 |
- ``deprecation.rst`` - deprecations (removal in next major release), |
| 204 |
- ``feature.rst`` - new features, |
| 205 |
- ``bugfix.rst`` - bug fixes, |
| 206 |
- ``doc.rst`` - documentation improvements, |
| 207 |
- ``packaging.rst`` - packaging updates and notes for downstreams, |
| 208 |
- ``contrib.rst`` - contributor-facing changes, |
| 209 |
- ``misc.rst`` - miscellaneous internal changes. |
| 210 |
|
| 211 |
Thus if your issue or PR number is ``1234`` and this change is fixing a bug, then you would create a file |
| 212 |
``docs/changelog/1234.bugfix.rst``. PRs can span multiple categories by creating multiple files (for instance, if you |
| 213 |
added a feature and deprecated/removed the old feature at the same time, you would create |
| 214 |
``docs/changelog/1234.bugfix.rst`` and ``docs/changelog/1234.deprecation.rst``). Likewise if a PR touches multiple |
| 215 |
issues/PRs you may create a file for each of them with the same contents and :pypi:`towncrier` will deduplicate them. |
| 216 |
|
| 217 |
Contents of a changelog entry |
| 218 |
----------------------------- |
| 219 |
|
| 220 |
The content of this file is reStructuredText formatted text that will be used as the content of the changelog entry. You |
| 221 |
do not need to reference the issue or PR numbers here as towncrier will automatically add a reference to all of the |
| 222 |
affected issues when rendering the changelog. You may append ``- by :user:USERNAME``, with a GitHub username in |
| 223 |
backticks, if you wish. |
| 224 |
|
| 225 |
In order to maintain a consistent style in the ``changelog.rst`` file, it is preferred to keep the entries to the point, |
| 226 |
in sentence case, shorter than 120 characters and in an imperative tone -- an entry should complete the sentence ``This |
| 227 |
change will …``. In rare cases, where one line is not enough, use a summary line in an imperative tone followed by a |
| 228 |
blank line separating it from a description of the feature/change in one or more paragraphs, each wrapped at 120 |
| 229 |
characters. Remember that a changelog entry is meant for end users and should only contain details relevant to an end |
| 230 |
user. |
| 231 |
|
| 232 |
An example of ``docs/changelog/####.bugfix.rst`` contents is: |
| 233 |
|
| 234 |
.. code-block:: |
| 235 |
|
| 236 |
Instead of raising ``UnicodeDecodeError`` when command output includes non-utf-8 bytes, ``tox`` will now use |
| 237 |
``surrogateescape`` error handling to convert the unrecognized bytes to escape sequences according to :pep:`383` |
| 238 |
- by :user:`masenf` |
| 239 |
|
| 240 |
Becoming a maintainer |
| 241 |
===================== |
| 242 |
|
| 243 |
If you want to become an official maintainer, start by helping out. As a first step, we welcome you to triage issues on |
| 244 |
tox's issue tracker. tox maintainers provide triage abilities to contributors once they have been around for some time |
| 245 |
and contributed positively to the project. This is optional and highly recommended for becoming a tox maintainer. Later, |
| 246 |
when you think you're ready, get in touch with one of the maintainers and they will initiate a vote among the existing |
| 247 |
maintainers. |
| 248 |
|
| 249 |
.. note:: |
| 250 |
|
| 251 |
Upon becoming a maintainer, a person should be given access to various tox-related tooling across multiple |
| 252 |
platforms. These are noted here for future reference by the maintainers: |
| 253 |
|
| 254 |
- GitHub Push Access (provides also CI administration capabilities) |
| 255 |
- PyPI Publishing Access |
| 256 |
- ReadTheDocs Administration capabilities (the root domain `tox.wiki <https://tox.wiki/en/latest/>`_ is currently |
| 257 |
owned and maintained by the primary maintainer and author ``Bernat Gabor``; bought via `Porkbun |
| 258 |
<https://porkbun.com/>`_ -- reach out to him directly for any changes). |
| 259 |
|
| 260 |
Creating a new release |
| 261 |
====================== |
| 262 |
|
| 263 |
tox supports two methods for preparing releases: |
| 264 |
|
| 265 |
Method 1: Local release (requires git access) |
| 266 |
--------------------------------------------- |
| 267 |
|
| 268 |
.. code-block:: shell |
| 269 |
|
| 270 |
tox r -e release -- <version> |
| 271 |
|
| 272 |
Example: |
| 273 |
|
| 274 |
.. code-block:: shell |
| 275 |
|
| 276 |
tox r -e release -- 4.27.0 |
| 277 |
|
| 278 |
This will: |
| 279 |
|
| 280 |
1. Create a ``release-<version>`` branch from upstream/main. |
| 281 |
2. Generate changelog using towncrier. |
| 282 |
3. Commit changes with message "release <version>". |
| 283 |
4. Tag the commit with the version number. |
| 284 |
5. Force-push to main and push the tag. |
| 285 |
6. Clean up local branches. |
| 286 |
|
| 287 |
Requirements: |
| 288 |
|
| 289 |
- Write access to tox-dev/tox repository. |
| 290 |
- Configured git remote pointing to tox-dev/tox (typically named ``upstream``). |
| 291 |
|
| 292 |
.. code-block:: shell |
| 293 |
|
| 294 |
git remote add upstream [email protected]:tox-dev/tox.git |
| 295 |
|
| 296 |
- Local dependencies installed via tox. |
| 297 |
|
| 298 |
Method 2: GitHub Actions workflow dispatch |
| 299 |
------------------------------------------ |
| 300 |
|
| 301 |
Navigate to `Actions > Prepare Release <https://github.com/tox-dev/tox/actions/workflows/prepare-release.yaml>`_ and: |
| 302 |
|
| 303 |
1. Click "Run workflow". |
| 304 |
2. Select the branch (usually ``main``). |
| 305 |
3. Choose the version bump type: |
| 306 |
|
| 307 |
- ``auto`` (default) - Automatically bump minor if feature changelogs exist, otherwise bump patch. |
| 308 |
- ``major`` - Bump major version (e.g., 4.0.0 → 5.0.0). |
| 309 |
- ``minor`` - Bump minor version (e.g., 4.27.0 → 4.28.0). |
| 310 |
- ``patch`` - Bump patch version (e.g., 4.27.0 → 4.27.1). |
| 311 |
|
| 312 |
4. Click "Run workflow". |
| 313 |
|
| 314 |
The workflow executes the same ``tasks/release.py`` script in a clean CI environment. |
| 315 |
|
| 316 |
Requirements: |
| 317 |
|
| 318 |
- Write access to tox-dev/tox repository (workflow permissions). |
| 319 |
- For repositories with branch protection on ``main``, a ``RELEASE_PAT`` secret must be configured in the |
| 320 |
``release-auth`` environment with a fine-grained Personal Access Token that has permissions to bypass branch |
| 321 |
protection rules. |
| 322 |
- Maintainer approval is required to trigger the workflow (configured via environment protection rules). |
| 323 |
|
| 324 |
After release preparation |
| 325 |
------------------------- |
| 326 |
|
| 327 |
Both methods push a tag to the repository. The tag push automatically triggers the ``release.yaml`` workflow which: |
| 328 |
|
| 329 |
1. Builds Python packages (sdist + wheel). |
| 330 |
2. Publishes to PyPI via trusted publishing. |
| 331 |
|
| 332 |
.. note:: |
| 333 |
|
| 334 |
- Both methods force-push to main (ensure no concurrent work). |
| 335 |
- The release process is atomic and should not be interrupted. |
| 336 |
- Failed releases can be retried with the same version number. |
| 337 |
|
| 338 |
.. _current-maintainers: |
| 339 |
|
| 340 |
Current maintainers |
| 341 |
------------------- |
| 342 |
|
| 343 |
- :user:`Bernát Gábor <gaborbernat>` |
| 344 |
- :user:`Jürgen Gmach <jugmac00>` |
| 345 |
- :user:`Rahul Devikar <rahuldevikar>` |
| 346 |
|
| 347 |
Previous maintainers |
| 348 |
-------------------- |
| 349 |
|
| 350 |
- :user:`Anthony Sottile <asottile>` |
| 351 |
- :user:`Masen Furer <masenf>` |
| 352 |
- :user:`Oliver Bestwalter <obestwalter>` |