Debian Codegraph @

docs/development.rst

raw
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>`