Contributing

There are lots of ways to contribute, from adding new features via pull requests to opening issues for missing features. Check out our issues list and filter for good first issues to find something we think you could tackle.

We recommend creating a Python 3 virtual environment (or using pipenv) before you start coding to keep the packages you need for nio separate from the packages you might need for other projects. Throughout the rest of the document, we’ll assume you’re working in your virtual environment.

Prerequisites

You’ll need to install the following:

You’ll also need to install some pip packages:

pip install -r test-requirements.txt
pip install -r rtd-requirements.txt

Testing

As you write, you may want to test your changes. You can add new tests and test files in tests/ to be picked up by pytest. To run the full test suite (please do this before submitting your pull request!), run

make test

If you only want to test your changes (and not run all of the test suite), you can run the following:

python3 -m pytest --benchmark-disable tests/your-test.py

Getting ready for a pull request

Get early feedback. You don’t need to perfect your changes to submit them; early feedback can help guide you in the right direction, especially if you’re struggling.

Make sure any new classes or methods you’ve added are properly documented, and if you’ve changed any existing methods make sure their docstrings are still up-to-date. It’s really important to have good documentation because you encourage other people to use that great feature you just added!

Before you submit your code for discussion, please make sure your code passes the test suite by reading Testing. Next, run make typecheck to verify that mypy is happy with the types in your code. Not sure about an error you got from either? No worries; submit your changes and we’ll talk about it.

When ready, push your changes to a fork of poljar/matrix-nio and open up a pull request. Give us a bit of a description of what changes you’ve made and why. If you are trying to close an open issue, you can link to it just by writing “Closes #104” in the description.

Adding documentation

Writing might be hard, but with a few instructions we’ll get you started. As you code, you can just write docstrings in your classes and methods, but if you want to document the architecture of nio (and we’d love if you did!) you can help us write documentation in the reStructuredText format.

You’ll need to install Sphinx if you’d like to preview your changes:

pip install sphinx

Once that is done, edit the .rst files in doc/ and run make html in the same directory. You’ll now have HTML pages in doc/build/html you can review.