rich/CONTRIBUTING.md

Contributing to Rich

This project welcomes contributions in the form of Pull Requests. For clear bug-fixes / typos etc. just submit a PR. For new features or if there is any doubt in how to fix a bug, you might want to open an issue prior to starting work, or email willmcgugan+rich@gmail.com to discuss it first.

Prerequisites

Rich uses poetry for packaging and dependency management. To start developing with Rich, install Poetry using the recommended method.

Next, you'll need to create a fork (your own personal copy) of the Rich repository, and clone that fork on to your local machine. GitHub offers a great tutorial for this process here. After following this guide, you'll have a local copy of the Rich project installed.

Enter the directory containing your copy of Rich (cd rich).

Poetry can be used to create an isolated virtual environment for the project:

poetry shell

The first time we run poetry shell, such an isolated environment is created and forever associated with our project. Any time we wish to enter this virtual environment again, we simply run poetry shell again.

Now we can install the dependencies of Rich into the virtual environment:

poetry install

The rest of this guide assumes you're inside the virtual environment. If you're having difficulty running any of the commands that follow, ensure you're inside the virtual environment by running poetry shell.

Developing

At this point, you're ready to start developing. Some things to consider while developing Rich code include:

• Ensure new code is documented in docstrings
• Avoid abbreviations in variable or class names
• Aim for consistency in coding style and API design

Before each commit, you should:

1. Run the tests and ensure they pass
2. Ensure type-checking passes
3. Format the code using black

These steps are described in the following sections.

Tests

Run tests with the following command:

make test

Or if you don't have make, run the following:

pytest --cov-report term-missing --cov=rich tests/ -vv

New code should ideally have tests and not break existing tests.

The "Coverage Report" that gets printed to the terminal after the tests run can be used to identify lines of code that haven't been covered by tests. If any of the new lines you've added or modified appear in this report, you should strongly consider adding tests which exercise them.

Type Checking

Rich uses type annotations throughout, and mypy to do the checking. Run the following to type check Rich:

make typecheck

Or if you don't have make:

mypy -p rich --config-file= --ignore-missing-imports --no-implicit-optional --warn-unreachable

Please add type annotations for all new code, and ensure that type checking succeeds before creating a pull request.

Code Formatting

Rich uses black for code formatting. I recommend setting up black in your editor to format on save.

To run black from the command line, use make format-check to check your formatting, and use make format to format and write to the files.

Consider Documentation

Consider whether the change you made would benefit from documentation - if the feature has any user impact at all, the answer is almost certainly yes! Documentation can be found in the docs directory. There are some additional dependencies required to build the documentation. These dependencies can be installed by running (from the docs directory):

pip install -r requirements.txt

After updating the documentation, you can build them (from the project root directory) by running:

make docs

This will generate the static HTML for the documentation site at docs/build/html.

Update CHANGELOG and CONTRIBUTORS

Before submitting your pull request, update the CHANGELOG.md file describing, briefly, what you've done. Be sure to follow the format seen in the rest of the document.

If this is your first time contributing to Rich:

1. Welcome!
2. Be sure to add your name to CONTRIBUTORS.md.

Pre-Commit

We strongly recommend you install the pre-commit hooks included in the repository. These automatically run some of the checks described earlier each time you run git commit, and over time can reduce development overhead quite considerably.

Creating A Pull Request

Once your happy with your change and have ensured that all steps above have been followed (and checks have passed), you can create a pull request. GitHub offers a guide on how to do this here. Please ensure that you include a good description of what your change does in your pull request, and link it to any relevant issues or discussions.

When you create your pull request, we'll run the checks described earlier. If they fail, please attempt to fix them as we're unlikely to be able to review your code until then. If you've exhausted all options on trying to fix a failing check, feel free to leave a note saying so in the pull request and someone may be able to offer assistance.

Code Review

After the checks in your pull request pass, someone will review your code. There may be some discussion and, in most cases, a few iterations will be required to find a solution that works best.

Afterwards

When the pull request is approved, it will be merged into the master branch. Your change will only be available to users the next time Rich is released.