Adding documentation¶

You might have the best software in the world - but if nobody knows how to use it, what's the point? Documentation can always be improved - and we need your help!

Documentation forms¶

BeeWare Docs Tools's documentation is written using MkDocs and Markdown. We aim to follow the Diataxis framework for structuring documentation.

The Diataxis framework describes four "forms" of documentation:

Tutorial - A guided learning experience, with a specific project endpoint.
How-to guide - Instructions that guide the reader towards a specific goal or outcome.
Topic guide - A discussion of a single idea, explained in such a way that the underlying concepts are clear.
Reference - Technical descriptions of specific APIs or other interfaces.

Before beginning any documentation contribution, it's important to identify which form is the best fit. Many documentation proposals will be initial described as a request for "a tutorial on X" - but in most cases, what is actually required is how-to, topic guide, or improved reference information.

As an example, consider the task of writing documentation about baking cookies.

Tutorial¶

A tutorial is an introduction, particularly one focused at beginners, the goal of which should be getting the reader from a clean starting point to a finished product. It requires very specific instructions, and detailed explanations that put the tutorial steps in context. You must assume nothing about the reader's experience with the tool being explained, although it's reasonable to assume some basic Python proficiency.

The tutorial should contain regular checkpoints where the reader can establish that they have succeeded in doing what has been described. At each checkpoint, success criteria should be clear. Known failure cases should be clearly outlined, including explanations of any likely errors or problems the reader might experience. Things that change as a result of actions the reader has taken should be pointed out, even if seemingly obvious. Repetition is encouraged, especially if you're trying to establish a best practice or common processes. Explanations of internals should be avoided, as should alternative paths to the same outcome.

A tutorial on baking cookies is more than just a recipe. The instructions in a tutorial should be accessible to someone who has never baked before (such as a child), and would need to account for things that an experienced baker would take for granted, such as how to cream sugar and butter, the process of pre-heating the oven, or how long cookies should be left to cool before eating. The goal of the tutorial isn't to produce a cookie - it's to convey the fundamentals of baking. The resulting cookie is the tasty treat that convinces someone to undertake the tutorial in the first place.

How-to guide¶

A how-to guide should focus on a specific real-world use-case and practical outcomes, rather than theoretical explanations. Unlike a tutorial, you can assume some familiarity with existing tools. The reader should be able to follow the guide from beginning to end and reach the goal, but they may need some existing knowledge to do so. It should include a set of concrete instructions or logical steps that need to be followed to achieve the goal of the guide.

A recipe in a cookbook is a good example of a how-to guide. There are many recipes for chocolate chip cookies, and they will all share common features, but any specific recipe should be possible to follow from beginning to end, and result in a consistent outcome. A good chocolate chip cookie recipe won't digress into the relative merits of different types of sugar or flour, or give detailed instructions on basic technique or process; it will include only the ingredients and instructions for baking a batch of cookies, assuming the reader has basic familiarity with baking.

Topic guide¶

A topic guide describes a single subject or idea. It may include example code or instructions, but it is much more focused on providing a high-level picture of an overall concept. It may include opinions and alternate perspectives, but the focus on the specific topic of the guide should be maintained.

A topic guide on baking cookies might dig into the history of cookies as a baked product, explore that way that industrialized processes result in different types of cookies compared to homemade cookies, or suggest ways that cookies can be incorporated into a balanced diet. By itself, it wouldn't be a very useful document to follow if you wanted to bake a cookie, but it might provide the background that would enable someone familiar with baking to successfully customize an existing cookie recipe.

Reference¶

Reference documentation is information oriented, describing specifics of operation of a tool library. They can quite often be generated from the code itself, but good API documentation may require further explanations and context. While it may sometimes include examples of usage, detailed explanations should be avoided.

A reference guide in baking might describe the types of sugar that could be used, and detail their properties when used in baking. It would describe literal facts about sugar, but a broader discussion about choosing between sugar types should be the subject of a how-to or topic guide. The nutritional information found on most packaged foods would be considered reference documentation.

Documentation style¶

BeeWare Docs Tools's documentation follows the guidelines outlined in the documentation style guide. This guide includes basic style and formatting, and the process for the spelling check. It also covers various Markdown syntax details, such as reference link syntax, tips for working with code blocks, and image handling.

Contributing documentation¶

Proposing new documentation

So you've got an idea about an improvement for BeeWare Docs Tools - how do you submit that idea for consideration?

Do your research¶

The first step is to search the BeeWare Docs Tools issue tracker for existing feature issues (issues tagged "enhancement"), documentation issues (issues tagged "documentation"), or Discussion threads to see if the idea has been suggested before. If it has, and you have new context or ideas to add, include them in the existing thread. If you would like assistance with your research, you can ask in the #dev channel on the BeeWare Discord. We may be able to point you in the direction of existing threads, provide context of which you may not be aware, or connect your idea to another idea that might not immediately seem related.

Discuss the idea¶

If you don't find any existing references to your idea, start a Discussion thread. Provide a high-level description of the purpose and use case for your idea. Include any thoughts you have on what the feature would look like, if implemented, such as the general shape of an API, the visual appearance of a capability, or the document that would be added. If applicable, you should also include any research you have done on how your idea would manifest on different platforms.

Once the Discussion thread is opened, the BeeWare team and the rest of the community will respond. The core team will aim to provide at least an initial impression of your idea within two business days. If an idea is especially complex, a more detailed analysis might take up to a week. Events like holidays and conferences might cause those timelines to be slightly longer.

This is your opportunity to participate in a conversation about your idea. We may ask for more details or context. Other members of the community may also get involved in the discussion, providing other perspectives, suggestions or counter-proposals. The outcome of this discussion will determine the next steps.

It's important to understand that not all ideas will be accepted. The reason this process starts with a proposal is to avoid you putting in all the work, only to find out there is a reason your change won't be accepted.

This doesn't mean it wasn't a good idea! There may be technical reasons it can't be implemented. For example, we might reject an idea if:

It would be difficult or impossible to implement reliably across all supported platforms; or
It would be difficult to maintain, or maintenance would require access to technology or software that isn't widely available; or
It serves a niche audience, but imposes significant overhead on other users.

If we determine that your idea isn't a good fit, it doesn't necessarily mean you should give up on it. While we may reject a specific idea, we may be a lot more amenable to adding a plugin interface or other extension point that would allow you to maintain the same feature as an external library. That way you can have the feature, but without the specific maintenance concerns or limitations of the feature becoming a constraint on the project itself.

Convert to a formal feature request¶

Once the discussion has reached a consensus on the form of a feature, you can create a new feature request issue, in the BeeWare Docs Tools issue tracker, that summarizes the discussion, linking to the discussion for context.

You don't have to implement your feature proposal yourself; you can open an issue with the details of what you're proposing. However, simply posting the issue doesn't mean it's going to be implemented for you. You'll need to wait for it to potentially get picked up by someone else interested in the same feature, whether that means another community member or the core team; however this is not guaranteed to happen. If you want the guarantee implementation, you'll need to implement it yourself, or pay someone else to implement it for you.

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.

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 -U -e . --group dev

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

(.venv) C:\...>python -m pip install -U -e . --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!

Work from a 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.

Working off your main branch also makes it difficult for you after you complete your first pull request. If you want to work on a second pull request, you will need to have a "clean" copy of the upstream project's main branch on which to base your second contribution; if you've made your first contribution from your main branch, you no longer have that clean version available.

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're fixing a bug that causes build issues on Windows 11, you might create a feature branch fix-win11-build. 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-build feature branch, run:

macOSLinuxWindows

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

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

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

Avoid scope creep

"Scope creep" happens when the list of problems resolved or features implemented by a single contribution grows significantly beyond what was intended when the work began. You start with a simple issue; you discover a closely related problem, and decide to include that fix as well; then a third... before you know it, you've got a pull request that closes 5 issues and adds 3 new features, including dozens of files.

Scope creep happens to everyone. It is a concept that is all too familiar to seasoned developers; we've all done it multiple times, and experienced all the issues that come with it.

There are very practical reasons to avoid scope creep. The larger a contribution gets, the more difficult it is to work with. It becomes harder to identify edge cases or potential problems, which means overall quality of the contribution may be diminished. Reviews also become more challenging when the reviewer needs to deal with multiple, potentially unrelated, contexts. A larger contribution means more review comments, and as a contributor, it can become difficult to follow multiple review threads. Even your GitHub experience will suffer - GitHub's UI will slow down as the size of a PR grows, meaning navigating the files through the GitHub interface and attempting to leave review comments becomes increasingly difficult.

Any time you find a reason to add anything to your contribution that isn't explicitly part of the original proposal or bug report, you should consider whether you're heading into scope creep. Are there two distinct features that could be implemented separately? Could a feature be implemented with a known limitation or bug, and that bug fixed in a follow-up pull request? Is one part of a bug fix independent of another? If part of a change can be left out without altering the original contribution, it probably should be.

Developing software is always a process of incremental improvement. Each individual contribution should leave the code base in a better state as a result of being merged, but it's entirely acceptable to leave bugs or parts of features as work for future improvement. That might mean breaking a pull request into multiple parts that can be reviewed independently, or logging an issue so that someone else can investigate and resolve the problem.

Limiting the scope of each contribution helps everyone involved, including you. Your reviewers, and even you, will appreciate it.

Building documentation

Before making any changes to BeeWare Docs Tools's documentation, it is helpful to confirm that you can build the existing documentation.

You must have a Python 3.13 interpreter installed and available on your path (i.e., python3.13 must start a Python 3.13 interpreter).

BeeWare Docs Tools uses tox for building documentation. The following tox commands must be run from the same location as the tox.ini file, which is in the root directory of the project.

Live documentation preview¶

To support rapid editing of documentation, BeeWare Docs Tools has a "live preview" mode.

The live preview will build with warnings!

The live serve is available for iterating on your documentation updates. While you're in the process of updating things, you may introduce a markup issue. Issues considered a WARNING will cause a standard build to fail, however, the live serve is set up to indicate warnings in the console output, while continuing to build. This allows you to iterate without needing to restart the live preview.

A WARNING is different from an ERROR. If you introduce an issue that is considered an ERROR, the live serve will fail, and require a restart. It will not start up again until the WARNING issue is resolved.

To start the live server:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

This will build the documentation, start a web server to serve the documentation, and watch the file system for any changes to the documentation source.

Once the server is started, you'll see something like the following in the console output:

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

Open a browser, and navigate to the URL provided. Now you can begin iterating on the documentation. If a change is detected, the documentation will be rebuilt, and any browser viewing the modified page will be automatically refreshed.

docs-live is an initial step

Running docs-live to work with the live server is meant for initial iterating. You should always run a local build before submitting a pull request.

Local build¶

Once you're done iterating, you'll need to do a local build of the documentation. This build process is designed to fail if there are any markup problems. This allows you to catch anything you might have missed with the live server.

Generating a local build¶

To generate a local build:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

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

The output of this build will be in the _build directory in the root of the project.

Generating a local translated build¶

BeeWare Docs Tools's documentation is translated into multiple languages. Updates to the English documentation have the potential lead to issues in the other language builds. It is important to verify all builds are working before submitting a pull request.

To generate a build of all available translations:

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

The output of each language build will be in the associated _build/html/<languagecode> directory, where <languagecode> is the two- or five-character language code associated with the specific language (e.g. fr for French, it for Italian, etc.).

If you find an issue with a single build, you can run that individual build separately by running tox -e docs-<languagecode>. For example, to build only the French documentation, run:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

The output of a single-language build will be in the _build directory.

Documentation linting¶

The build process will identify Markdown problems, but BeeWare Docs Tools performs some additional checks for style and formatting, known as "linting". To run the lint checks:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

This will validate the documentation does not contain:

dead hyperlinks
misspelled words

If a valid spelling of a word is identified as misspelled, then add the word to the list in docs/spelling_wordlist. This will add the word to the spellchecker's dictionary. When adding to this list, remember:

We prefer US spelling, with some liberties for programming-specific colloquialism (e.g., "apps") and verbing of nouns (e.g., "scrollable")
Any reference to a product name should use the product's preferred capitalization. (e.g., "macOS", "GTK", "pytest", "Pygame", "PyScript").
If a term is being used "as code", then it should be quoted as a literal (like this) rather than being added to the dictionary.

Writing documentation

These are the steps to follow to write your documentation contribution to BeeWare Docs Tools.

Updating existing documentation¶

If you're editing the existing docs, you'll need to locate the file in the /docs/en directory. The file structure follows the page structure, so you can locate the file using the documentation URL.

Adding new documentation¶

If you're adding a new document, there are a few more steps involved.

You'll need to create the document in the appropriate location within the docs/en directory. For discussion, we'll say you're adding a new document with the filename new_doc.md.

Then, you'll need to update the docs/en/SUMMARY.md file to include your new file. SUMMARY.md is organized to basically reflect the docs/en directory structure, but, more importantly, directly determines the structure of the left sidebar. If you locate the section where you intend to include new_doc.md, you do not need to change anything in SUMMARY.md if you see a wildcard path listed. For example:

- ./path/to/directory/*

If the section where you intend to include new_doc.md is a list of individual Markdown links, you'll need to add an explicit link to yours. For example:

- [My new document](new_doc.md)

Writing your documentation¶

You can now open the desired file into your editor, and begin writing.

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

Add a change note

BeeWare Docs Tools uses towncrier to assist in building the release notes for each release. When you submit a pull request, it must include a change note - this change note will become the entry in the release notes describing the change that has been made.

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 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 a 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 "marketing" 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 description for the benefit of users, who may not have knowledge of internals.

For example, if you fix a bug related to project naming, the commit message might read:

Apply stronger regular expression check to disallow project names that begin with digits.

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.

Submit a pull request

Now that you've committed all your changes, you're ready to submit a pull request. To ensure you have a smooth review process, there are a number of steps you should take.

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. In the following example, a code formatting issue was found by the ruff check:

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

In this case, ruff automatically fixed the problem; so you can then re-add any files that were modified as a result of the pre-commit checks, and re-commit the change. However, some checks will require you to make manual modifications. Once you've made those changes, re-add any modified files, and re-commit.

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
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Once everything passes, you'll see a message indicating the commit has been finalized, and your git log will show your commit as the most recent addition. You're now ready to push to GitHub.

Push your changes to GitHub and create your pull request¶

The first time you push to GitHub, you'll be provided a URL that takes you directly to the GitHub page to create a new pull request. Follow the URL and create your pull request.

The following shows an example of what to expect on push, with the URL highlighted.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.git
 * [new branch]      fix-win11-build -> fix-win11-build

If you've previously pushed the current branch to GitHub, you won't receive the URL again. However, there are other ways to get to the PR creation URL:

Navigate to the upstream repository, click on "Pull Requests" followed by "New pull request", and choose the from which you want to submit your pull request.
If you pushed recently, navigate to the upstream repository, locate the banner above the list of files that indicates the repo has "had recent pushes", and click the "Compare & pull request" button.
Use the GitHub CLI gh pr create command, and fill out the prompts.
Use the GitHub CLI gh pr create --web command to open a web browser to the PR creation page.

Any of these options will enable you to create your new pull request.

The GitHub CLI: gh

GitHub provides the GitHub CLI, which gives you access to many of the features of GitHub from your terminal, through the gh command. The GitHub CLI documentation covers all the features.

Pull request content¶

A pull request title must be informative, clear, and concise. Try to keep it short if possible, but longer titles are acceptable, if needed. A good PR title should give a person without any context a reasonably solid idea of what bug or feature is implemented by your PR.

The PR description must clearly reflect the changes in the PR. A person without any context should be able to read your description, and gain a relatively complete understanding of why the change is being made. Avoid jokes, idioms, colloquialisms, and unnecessary formatting, such as using all caps or excessive punctuation; this is meant to be a straightforward explanation of what is happening in your PR, and avoiding those things makes the description more accessible to others.

If there are any reproduction cases, or any testing regimen that you used that are not already a part of the changes present in the PR, they should be explained and included in the PR. The explanation should include how to run them, and what to do to reproduce the desired outcome.

If your pull request will resolve issue #1234, you should include the text Fixes #1234 in your pull request description. This will cause the issue to be automatically closed when the pull request is merged. You can refer to other discussions, issues or pull requests using the same #1234 syntax. You can refer to an issue on a different repository by prefixing the number with - for example python/cpython#1234 would refer to issue 1234 on the CPython repository.

Continuous integration¶

Continuous integration, or CI, is the process of running automated checks on your pull request. This can include simple checks like ensuring code is correctly formatted; but it also includes running the test suite, and building documentation.

There are any number of changes that can result in CI failures. Broadly speaking, we won't review a PR that isn't passing CI. If you create a pull requests and CI fails, we won't begin your review until it is passing. If your changes result in a failure, it is your responsibility to look into the reason, and resolve the issue.

When CI fails, the failure links will show up at the bottom of the PR page, under the heading "Some checks were not successful". You'll see a list of failed checks, which, will show up at the top of the list of all checks if there are passing checks as well. If you click on the failure link, it will take you to the log. The log often provides all the information you need to figure out what caused the failure. Read through the log and try to figure out why the failure is occurring, and then do what's necessary to resolve it.

Occasionally, a CI check will fail for reasons that are unrelated to your changes. This could be due to an issue on the machine that runs the CI check; or because a CI check is unstable. If you see a failure, and you're fairly certain it's unrelated to your changes, add a comment to your PR to that effect, and we will look into it.

To trigger a new CI run, you need to push new changes to your branch.

If you find yourself in a situation where you need help getting CI to pass, leave a comment on the PR letting us know and we'll do what we can to help.

The pre-commit and towncrier checks

If either the pre-commit or towncrier checks fail, it will block most of the rest of the CI checks from running. You'll need to resolve the applicable issues before the full set of checks will run.

We have limited CI resources. It is important to understand that every time you push to the branch, CI will start. If you're going to make a number of changes, it's better to make those changes locally, push them all at once. CI will only run on the most recent commit in a batch, minimizing the load on our CI system.

The process of submitting your PR is not done until it's passing CI, or you can provide an explanation for why it's not.