Fixing an issue¶

BeeWare Docs Tools tracks a list of known issues. Any of these issues are candidates to be worked on. This list can be filtered in various ways, to help narrow down an option for you. You can filter by platform, so you can focus on issues that affect the platforms you're able to test on. There's also a filter for good first issues. These issues have been identified as problems that have a known cause, and we believe the fix should be relatively straightforward (although we might be wrong in our analysis).

If an issue is more than 6 months old, it's entirely possible that the issue has been resolved, so the first step is to verify that you can reproduce the problem. Use the information provided in the bug report to try and reproduce the problem. If you can't reproduce the problem, report what you have found as a comment on the ticket, and pick another ticket.

If you can reproduce the problem - try to fix it! Work out what combination of code is implementing the feature, and see if you can work out what isn't working correctly.

Even if you can't fix the problem, reporting anything you discover as a comment on the ticket is worthwhile. If you can find the source of the problem, but not the fix, that knowledge will often be enough for someone who knows more about a platform to solve the problem. A good reproduction case (a sample app that does nothing but reproduce the problem) can be a huge help.

Contributing an issue fix¶

TODO: blurb.

Set up a development environment

Contributing to BeeWare Docs Tools requires you to set up a development environment.

Prerequisites¶

You'll need to install the following prerequisites.

macOSLinuxWindows

BeeWare Docs Tools requires Python 3.10+. You will also need a method for managing virtual environments (such as venv).

You can verify the version of Python that you have installed by running:

$ python3 --version

If you have more than one version of Python installed, you may need to replace python3 with a specific version number (e.g., python3.13)

We recommend avoiding recently released version of Python (i.e., versions that have a ".0" or ".1" micro version number, like e.g., 3.14.0). This is because the tools needed to support Python on macOS often lag usually aren't available for recently released stable Python versions.

BeeWare Docs Tools requires Python 3.10+. You will also need a method for managing virtual environments (such as venv).

You can verify the version of Python that you have installed by running:

$ python3 --version

If you have more than one version of Python installed, you may need to replace python3 with a specific version number (e.g., python3.13)

We recommend avoiding recently released version of Python (i.e., versions that have a ".0" or ".1" micro version number, like e.g., 3.14.0). This is because the tools needed to support Python on Linux often lag usually aren't available for recently released stable Python versions.

BeeWare Docs Tools requires Python 3.10+. You will also need a method for managing virtual environments (such as venv).

You can verify the version of Python that you have installed by running:

C:\...>py -3 --version

If you have more than one version of Python installed, you may need to replace the -3 with a specific version number (e.g., -python3.13)

We recommend avoiding recently released version of Python (i.e., versions that have a ".0" or ".1" micro version number, like e.g., 3.14.0). This is because the tools needed to support Python on Windows often lag usually aren't available for recently released stable Python versions.

tl;dr - Quick start¶

Create your dev environment by running:

macOSLinuxWindows

$ git clone https://github.com/beeware/beeware-docs-tools.git
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ . .venv/bin/activate
(.venv) $ python -m pip install -U pip
(.venv) $ python -m pip install -Ue . --group dev
(.venv) $ pre-commit install

$ git clone https://github.com/beeware/beeware-docs-tools.git
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ . .venv/bin/activate
(.venv) $ python -m pip install -U pip
(.venv) $ python -m pip install -Ue . --group dev
(.venv) $ pre-commit install

C:\...>git clone https://github.com/beeware/beeware-docs-tools.git
C:\...>cd beeware-docs-tools
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) C:\...>python -m pip install -U pip
(.venv) C:\...>python -m pip install -Ue . --group dev
(.venv) C:\...>pre-commit install

Invoke checks and tests by running:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

Set up your development environment¶

The recommended way of setting up your development environment for BeeWare Docs Tools is to use a virtual environment, and then install the development version of BeeWare Docs Tools and its dependencies.

Clone the BeeWare Docs Tools repository¶

Next, go to the BeeWare Docs Tools page on GitHub, and, if you haven't already, fork the repository into your own account. Next, click on the "<> Code" button on your fork. If you have the GitHub desktop application installed on your computer, you can select "Open with GitHub Desktop"; otherwise, copy the HTTPS URL provided, and use it to clone the repository to your computer using the command line:

macOSLinuxWindows

Fork the BeeWare Docs Tools repository, and then:

$ git clone https://github.com/<your username>/beeware-docs-tools.git

(substituting your GitHub username)

Fork the BeeWare Docs Tools repository, and then:

$ git clone https://github.com/<your username>/beeware-docs-tools.git

(substituting your GitHub username)

Fork the BeeWare Docs Tools repository, and then:

C:\...>git clone https://github.com/<your username>/beeware-docs-tools.git

(substituting your GitHub username)

Create a virtual environment¶

To set up a virtual environment and upgrade pip, run:

macOSLinuxWindows

$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware-docs-tools
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Your prompt should now have a (.venv) prefix in front of it.

Install BeeWare Docs Tools¶

Now that you have the source code, you can do an editable install of BeeWare Docs Tools into your development environment. Run the following command:

macOSLinuxWindows

(.venv) $ python -m pip install -Ue . --group dev

(.venv) $ python -m pip install -Ue . --group dev

(.venv) C:\...>python -m pip install -Ue . --group dev

Enable pre-commit¶

BeeWare Docs Tools uses a tool called pre-commit to identify simple issues and standardize code formatting. It does this by installing a git hook that automatically runs a series of code linters prior to finalizing any git commit. To enable pre-commit, run:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Now you are ready to start hacking on BeeWare Docs Tools!

Reproduce the issue

You can't fix a problem if you don't have the problem in the first place. Therefore, reproducing the issue is a prerequisite to fixing it. In software, problems are commonly referred to as "bugs", and issues are often called "bug reports".

Someone has provided a bug report. You need to validate that the steps the reporter describes are resulting in the bug being reported. Can you reproduce the same result by doing exactly what was described in the report? If you can't, you need to figure out why.

Sometimes it's not even a bug; the person may have misread the documentation, or made a genuine mistake. This may indicate an issue with the documentation, such as being ambiguous or unclear. In that case, the fix for the issue may be updating the documentation to clarify the misunderstood instructions. As part of triage, you can update the bug report to indicate that the issue is with the documentation.

In an ideal situation, you have the same setup as the person who reported the bug, you follow the steps, and you're able to reproduce the bug. In many cases, though, it won't be so straightforward. Many bug reports include only vague explanations, and a vague set of conditions. The problem with that is, that bugs may vary based on the set of conditions involved, including how they're interacted with, various preconditions, operating system, operating system version, CPU architecture, or whether the user's machine is old and slow or new and fast. The more information we have about the situation surrounding the bug, the better. Try and reproduce the set of conditions that the reporter has provided. If you're unable to do so, your next step may need to be requesting more information from the person who reported the bug.

The best way to reproduce a bug is with the smallest possible example that still exhibits the issue. Most of the time reporters will not provide a minimum viable example, they will provide their large, complicated demo code. You'll want to reduce the report down to the simplest possible form that exhibits the issue; the best reproduction case is the smallest possible program. This reduction is itself helpful because it determines what the actual problem is. Essentially, anyone can take this example, run it, and it will result in the bug occurring.

Now that you've reproduced the bug, you're ready to move on to the next step.

Write, run, and test code

Write your code¶

You'll need to write the code necessary for triaging or fixing a bug, or for a feature implementation.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare Docs Tools uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

As with the full test suite, and the core, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare Docs Tools. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare Docs Tools maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare Docs Tools targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
TOTAL    7540      0   1040      0  100.0%

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

Name                                 Stmts   Miss Branch BrPart  Cover   Missing
--------------------------------------------------------------------------------
src/some/interesting_file.py           111      1     26      0  98.1%   170, 302-307, 320->335
--------------------------------------------------------------------------------
TOTAL                                 7540      1   1726      0  99.9%

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket... but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

Submit a pull request

Before you submit a pull request, there's a few bits of housekeeping to do.

Submit from a feature branch, not your `main` branch¶

Before you start working on your change, make sure you've created a branch. By default, when you clone your repository fork, you'll be checked out on your main branch. This is a direct copy of BeeWare Docs Tools's main branch.

While you can submit a pull request from your main branch, it's preferable if you don't do this. If you submit a pull request that is almost right, the core team member who reviews your pull request may be able to make the necessary changes, rather than giving feedback asking for a minor change. However, if you submit your pull request from your main branch, reviewers are prevented from making modifications.

Instead, you should make your changes on a feature branch. A feature branch has a simple name to identify the change that you've made. For example, if you've found a bug that causes a display problem on Windows 11, you might create a feature branch fix-win11-display. If your bug relates to a specific issue that has been reported, it's also common to reference that issue number in the branch name (e.g., fix-1234).

To create a fix-win11-display feature branch, run:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-display

(.venv) $ git switch -c fix-win11-display

(.venv) C:\...>git switch -c fix-win11-display

Commit your changes to this branch, then push to GitHub and create a pull request.

Working with pre-commit¶

When you commit any change, pre-commit will run automatically. If there are any issues found with the commit, this will cause your commit to fail. Where possible, pre-commit will make the changes needed to correct the problems it has found:

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

You can then re-add any files that were modified as a result of the pre-commit checks, and re-commit the change.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed

Once everything passes, you're ready for the next steps.

Add change information for release notes¶

When you submit this change as a pull request, you need to add a change note. BeeWare Docs Tools uses towncrier to automate building the release notes for each release. Every pull request must include at least one file in the changes/ directory that provides a short description of the change implemented by the pull request.

The change note should be in Markdown format, in a file that has name of the format <id>.<fragment type>.md. If the change you are proposing will fix a bug or implement a feature for which there is an existing issue number, the ID will be the number of that ticket. If the change has no corresponding issue, the PR number can be used as the ID. You won't know this PR number until you push the pull request, so the first CI pass will fail the towncrier check; add the change note and push a PR update and CI should then pass.

There are five allowed fragment types:

feature: The PR adds a new behavior or capability that wasn't previously possible (e.g., adding support for a new packaging format, or a new feature in an existing packaging format);
bugfix: The PR fixes a bug in the existing implementation;
doc: The PR is an significant improvement to documentation;
removal; The PR represents a backwards incompatible change in the BeeWare Docs Tools API; or
misc; A minor or administrative change (e.g., fixing a typo, a minor language clarification, or updating a dependency version) that doesn't need to be announced in the release notes.

This description in the change note should be a high level summary of the change from the perspective of the user, not a deep technical description or implementation detail. It is distinct from a commit message - a commit message describes what has been done so that future developers can follow the reasoning for a change; the change note is a "user facing" description. For example, if you fix a bug related to project naming, the commit message might read:

Disallow project names that begin with a number.

The corresponding change note would read something like:

Project names can no longer begin with a number.

Some PRs will introduce multiple features and fix multiple bugs, or introduce multiple backwards incompatible changes. In that case, the PR may have multiple change note files. If you need to associate two fragment types with the same ID, you can append a numerical suffix. For example, if PR 789 added a feature described by ticket 123, closed a bug described by ticket 234, and also made two backwards incompatible changes, you might have 4 change note files:

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

For more information about towncrier and fragment types see News Fragments. You can also see existing examples of news fragments in the changes directory of the BeeWare Docs Tools repository. If this folder is empty, it's likely because BeeWare Docs Tools has recently published a new release; change note files are deleted and combined to update the release notes with each release. You can look at that file to see the style of comment that is required; you can look at recently merged PRs to see how to format your change notes.

Fixing an issue¶

Contributing an issue fix¶

Prerequisites¶

tl;dr - Quick start¶

Set up your development environment¶

Clone the BeeWare Docs Tools repository¶

Create a virtual environment¶

Install BeeWare Docs Tools¶

Enable pre-commit¶

Write your code¶

Test-driven development¶

Run your code¶

Running tests and coverage¶

Running test variations¶

Run tests for multiple versions of Python¶

Run only the test suite¶

Run a subset of tests¶

Run the test suite for a specific Python version¶

Run the test suite without coverage (fast)¶

Code coverage¶

Understanding coverage results¶

Coverage report for host platform and Python version¶

Coverage report for host platform¶

Coverage reporting in HTML¶

It's not just about writing tests!¶

Submit from a feature branch, not your main branch¶

Working with pre-commit¶

Add change information for release notes¶

Submit from a feature branch, not your `main` branch¶