Contributing code to Briefcase

If you experience problems with Briefcase, log them on GitHub. If you want to contribute code, please fork the code and submit a pull request.

Setting up your development environment

The recommended way of setting up your development environment for Briefcase is to use a virtual environment, install the required dependencies and start coding:

macOSLinuxWindows

$ git clone https://github.com/beeware/briefcase.git
$ cd briefcase
$ python3 -m venv venv
$ . venv/bin/activate

To install all the development version of Briefcase, along with all it’s requirements, run the following commands within your virtual environment:

macOSLinuxWindows

$ (venv) pip install -e .

Now you are ready to start hacking! Have fun!

Briefcase uses PyTest for its own test suite. It uses tox to manage the testing process. To set up a testing environment and run the full test suite:

macOSLinuxWindows

$ (venv) pip install tox
$ (venv) tox

By default this will run the test suite multiple times, once on each Python version supported by Briefcase, as well as running some pre-commit checks of code style and validity. This can take a while, so if you want to speed up the process while developing, you can run the tests on one Python version only:

macOSLinuxWindows

(venv) $ tox -e py

Or, to run using a specific version of Python, e.g. when you want to use Python 3.7:

macOSLinuxWindows

(venv) $ tox -e py37

substituting the version number that you want to target. You can also specify one of the pre-commit checks flake8, docs or package to check code formatting, documentation syntax and packaging metadata, respectively.

Add change information for release notes

Briefcase uses towncrier to automate building release notes. To support this, every pull request needs to have a corresponding file in the changes/ directory that provides a short description of the change implemented by the pull request.

This description should be a high level summary of the change from the perspective of the user, not a deep technical description or implementation detail. It should also be written in past tense (i.e., “Added an option to enable X” or “Fixed handling of Y”).

See News Fragments for more details on the types of news fragments you can add. You can also see existing examples of news fragments in the changes/ folder.