Contributing to Arcade#
Arcade welcomes contributions, including:
Bug fixes
Implementations of requested features
Corrections & additions to the documentation
Improvements to the tests
If you’re looking for a way to contribute, try checking the currently active issues for one that needs work.
Before Making Changes#
Before working on an improvement, please make sure to open an issue if one does not already exist for it.
Tips:
Try to keep individual PRs to reasonable sizes
If you want to make large changes, please discuss them with Arcade’s developers beforehand
Discussion can happen in a GitHub issue’s comments or on Arcade’s Discord server.
After Making Changes#
After you finish your changes, you should do the following:
Test your changes according to the Testing section below
Submit a pull request from your fork to Arcade’s development branch.
The rest of the guide will help you get to this point & explain how to test in more detail.
Requirements#
Although using arcade only requires Python 3.8 or higher, development currently requires 3.9 or higher.
The rest of this guide assumes you’ve already done the following:
Changed directories into your local Arcade clone’s folder
Creating & using a virtual environment is also strongly recommended.
Installing Arcade in Editable Mode#
To install all necessary development dependencies, run this command in your terminal from inside the top level of the arcade directory:
pip install -e '.[dev]'
If you get an error like the one below, you probably need to update your pip version:
ERROR: File "setup.py" not found. Directory cannot be installed in editable mode: /home/user/Projects/arcade
(A "pyproject.toml" file was found, but editable mode currently requires a setup.py based build.)
Upgrade by running the following command:
pip install --upgrade pip
Mac & Linux users can improve their development experience further by following the optional steps at the end of this document.
Testing#
You should test your changes locally before submitting a pull request to make sure they work correctly & don’t break anything.
Ideally, you should also write unit tests for new features. See the tests folder in this repo for current tests.
Testing Code Changes#
First, run the below command to run our linting tools automatically. This will run Mypy and Ruff against Arcade. The first run of this may take some as MyPy will not have any caches built up. Sub-sequent runs will be much faster.
python make.py lint
If you want to run either of these tools individually, you can do
python make.py ruff
or
python make.py mypy
Now you run the framework’s unit tests with the following command:
python make.py test
Building & Testing Documentation#
Automatic Rebuild with Live Reload#
You can build & preview documentation locally using the following steps.
Run the doc build to build the web page files, and host a webserver to preview:
python make.py serve
You can now open http://localhost:8000 in your browser to preview the docs.
The doc/build/html
directory will contain the generated website files. When you change source files,
it will automatically regenerate, and browser tabs will automatically refresh to show your updates.
If you suspect the automatic rebuilds are failing to detect changes, you can run a simpler one-time build using the following instructions.
One-time build#
Run the doc build to build the web page files:
python make.py html
The doc/build/html
directory will contain the generated website files.
Start a local web server to preview the doc:
python -m http.server -d doc/build/html
You can now open http://localhost:8000 in your browser to preview the doc.
Be sure to re-run build & refresh to update after making changes!
Optional: Improve Ergonomics on Mac and Linux#
make.py shorthand#
On Mac & Linux, you can run the make script as ./make.py
instead of python make.py
.
For example, this command:
python make.py lint
can now be run this way:
./make.py lint
Enable Shell Completions#
On Mac & Linux, you can enable tab completion for commands on the following supported shells:
bash
(the most common default shell)zsh
fish
powershell
powersh
For example, if you have typed the following…
./make.py h
Tab completion would allow you to press tab to auto-complete the command:
./make.py html
Note that this may interfere if you work on other projects that also have a make.py file.
To enable this feature, most users can follow these steps:
Run
./make.py whichshell
to find out what your default shell isIf it is one of the supported shells, run
./make.py --install-completion $(basename "$SHELL")
Restart your terminal
If your default shell is not the shell you prefer using for arcade development, you may need to specify it to the command above directly instead of using auto-detection.