Contributor Guide#

Note

The Code of Conduct applies in all community spaces. If you are not familiar with our Code of Conduct policy, take a minute to read it before making your first contribution.

The ReactPy team welcomes contributions and contributors of all kinds - whether they come as code changes, participation in the discussions, opening issues and pointing out bugs, or simply sharing your work with your colleagues and friends. We’re excited to see how you can help move this project and community forward!

Everyone Can Contribute!#

Trust us, there’s so many ways to support the project. We’re always looking for people who can:

  • Improve our documentation

  • Teach and tell others about ReactPy

  • Share ideas for new features

  • Report bugs

  • Participate in general discussions

Still aren’t sure what you have to offer? Just ask us and we’ll help you make your first contribution.

Making a Pull Request#

To make your first code contribution to ReactPy, you’ll need to install Git (or Git Bash on Windows). Thankfully there are many helpful tutorials about how to get started. To make a change to ReactPy you’ll do the following:

Fork ReactPy:

Go to this URL and click the “Fork” button.

Clone your fork:

You use a git clone command to copy the code from GitHub to your computer.

Create a new branch:

You’ll git checkout -b your-first-branch to create a new space to start your work.

Prepare your Development Environment:

We explain in more detail below how to install all ReactPy’s dependencies.

Push your changes:

Once you’ve made changes to ReactPy, you’ll git push them to your fork.

Create a changelog entry:

Record your changes in the Changelog so we can publicize them in the next release.

Create a Pull Request:

We’ll review your changes, run some tests and equality checks and, with any luck, accept your request. At that point your contribution will be merged into the main codebase!

Development Environment#

Note

If you have any questions during set up or development post on our discussion board and we’ll answer them.

In order to develop ReactPy locally you’ll first need to install the following:

What to Install

How to Install

Python >= 3.9

https://realpython.com/installing-python/

Hatch

https://hatch.pypa.io/latest/install/

Poetry

https://python-poetry.org/docs/#installation

Git

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

NodeJS >= 14

https://nodejs.org/en/download/package-manager/

NPM >= 7.13

https://docs.npmjs.com/try-the-latest-stable-version-of-npm

Docker (optional)

https://docs.docker.com/get-docker/

Note

NodeJS distributes a version of NPM, but you’ll want to get the latest

Once done, you can clone a local copy of this repository:

git clone https://github.com/reactive-python/reactpy.git
cd reactpy

Then, you should be able to activate your development environment with:

hatch shell

From within the shell, to install the projects in this repository, you should then run:

invoke env

Project Structure#

This repository is set up to be able to manage many applications and libraries written in a variety of languages. All projects can be found under the src directory:

  • src/py/{project} - Python packages

  • src/js/app - ReactPy’s built-in JS client

  • src/js/packages/{project} - JS packages

At the root of the repository is a pyproject.toml file that contains scripts and their respective dependencies for managing all other projects. Most of these global scripts can be run via hatch run ... however, for more complex scripting tasks, we rely on Invoke. Scripts implements with Invoke can be found in tasks.py.

Running The Tests#

Tests exist for both Python and Javascript. These can be run with the following:

hatch run test-py
hatch run test-js

If you want to run tests for individual packages you’ll need to cd into the package directory and run the tests from there. For example, to run the tests just for the reactpy package you’d do:

cd src/py/reactpy
hatch run test --headed  # run the tests in a browser window

For Javascript, you’d do:

cd src/js/packages/event-to-object
npm run check:tests

Code Quality Checks#

Several tools are run on the codebase to help validate its quality. For the most part, if you set up your Development Environment with pre-commit to check your work before you commit it, then you’ll be notified when changes need to be made or, in the best case, changes will be made automatically for you.

The following are currently being used:

  • MyPy - a static type checker

  • Black - an opinionated code formatter

  • Flake8 - a style guide enforcement tool

  • Ruff - An extremely fast Python linter, written in Rust.

  • Prettier - a tool for automatically formatting various file types

  • EsLint - A Javascript linter

The most strict measure of quality enforced on the codebase is 100% test coverage in Python files. This means that every line of coded added to ReactPy requires a test case that exercises it. This doesn’t prevent all bugs, but it should ensure that we catch the most common ones.

If you need help understanding why code you’ve submitted does not pass these checks, then be sure to ask, either in the Community Forum or in your Pull Request.

Note

You can manually run hatch run lint --fix to auto format your code without having to do so via pre-commit. However, many IDEs have ways to automatically format upon saving a file (e.g. VSCode)

Building The Documentation#

To build and display the documentation locally run:

hatch run docs

This will compile the documentation from its source files into HTML, start a web server, and open a browser to display the now generated documentation. Whenever you change any source files the web server will automatically rebuild the documentation and refresh the page. Under the hood this is using sphinx-autobuild.

To run some of the examples in the documentation as if they were tests run:

hatch run test-docs

Building the documentation as it’s deployed in production requires Docker. Once you’ve installed Docker, you can run:

hatch run docs --docker

Where you can then navigate to http://localhost:5000..

Creating a Changelog Entry#

As part of your pull request, you’ll want to edit the Changelog by adding an entry describing what you’ve changed or improved. You should write an entry in the style of Keep a Changelog that falls under one of the following categories, and add it to the Unreleased section of the changelog:

  • Added - for new features.

  • Changed - for changes in existing functionality.

  • Deprecated - for soon-to-be removed features.

  • Removed - for now removed features.

  • Fixed - for any bug fixes.

  • Documented - for improvements to this documentation.

  • Security - in case of vulnerabilities.

If one of the sections doesn’t exist, add it. If it does already, add a bullet point under the relevant section. Your description should begin with a reference to the relevant issue or pull request number. Here’s a short example of what an unreleased changelog entry might look like:

Unreleased
----------

**Added**

- :pull:`123` - A really cool new feature

**Changed**

- :pull:`456` - The behavior of some existing feature

**Fixed**

- :issue:`789` - Some really bad bug

Hint

:issue: and :pull: refer to issue and pull request ticket numbers.

Release Process#

Creating a release for ReactPy involves two steps:

  1. Tagging a version

  2. Publishing a release

To tag a version you’ll run the following command:

nox -s tag -- <the-new-version>

Which will update the version for:

  • Python packages

  • Javascript packages

  • The changelog

You’ll be then prompted to confirm the auto-generated updates before those changes will be staged, committed, and pushed along with a new tag matching <the-new-version> which was specified earlier.

Lastly, to publish a release create one in GitHub. Because we pushed a tag using the command above, there should already be a saved tag you can target when authoring the release. The release needs a title and description. The title should simply be the version (same as the tag), and the description should simply use GitHub’s “Auto-generated release notes”.

Other Core Repositories#

ReactPy depends on, or is used by several other core projects. For documentation on them you should refer to their respective documentation in the links below: