CONTRIBUTING.rst

Contributing code to Matrix

Everyone is welcome to contribute code to Matrix (https://github.com/matrix-org), provided that they are willing to license their contributions under the same license as the project itself. We follow a simple 'inbound=outbound' model for contributions: the act of submitting an 'inbound' contribution means that the contributor agrees to license the code under the same terms as the project's overall 'outbound' license - in our case, this is almost always Apache Software License v2 (see LICENSE).

How to contribute

The preferred and easiest way to contribute changes to Matrix is to fork the relevant project on github, and then create a pull request to ask us to pull your changes into our repo (https://help.github.com/articles/using-pull-requests/)

The single biggest thing you need to know is: please base your changes on the develop branch - /not/ master.

We use the master branch to track the most recent release, so that folks who blindly clone the repo and automatically check out master get something that works. Develop is the unstable branch where all the development actually happens: the workflow is that contributors should fork the develop branch to make a 'feature' branch for a particular contribution, and then make a pull request to merge this back into the matrix.org 'official' develop branch. We use github's pull request workflow to review the contribution, and either ask you to make any refinements needed or merge it and make them ourselves. The changes will then land on master when we next do a release.

We use CircleCI and Travis CI for continuous integration. All pull requests to synapse get automatically tested by Travis and CircleCI. If your change breaks the build, this will be shown in GitHub, so please keep an eye on the pull request for feedback.

To run unit tests in a local development environment, you can use:

• tox -e py27 (requires tox to be installed by pip install tox) for SQLite-backed Synapse on Python 2.7.
• tox -e py35 for SQLite-backed Synapse on Python 3.5.
• tox -e py36 for SQLite-backed Synapse on Python 3.6.
• tox -e py27-postgres for PostgreSQL-backed Synapse on Python 2.7 (requires a running local PostgreSQL with access to create databases).
• ./test_postgresql.sh for PostgreSQL-backed Synapse on Python 2.7 (requires Docker). Entirely self-contained, recommended if you don't want to set up PostgreSQL yourself.

Docker images are available for running the integration tests (SyTest) locally, see the documentation in the SyTest repo for more information.

Code style

All Matrix projects have a well-defined code-style - and sometimes we've even got as far as documenting it... For instance, synapse's code style doc lives at https://github.com/matrix-org/synapse/tree/master/docs/code_style.rst.

Please ensure your changes match the cosmetic style of the existing project, and never mix cosmetic and functional changes in the same commit, as it makes it horribly hard to review otherwise.

Changelog

All changes, even minor ones, need a corresponding changelog / newsfragment entry. These are managed by Towncrier (https://github.com/hawkowl/towncrier).

To create a changelog entry, make a new file in the changelog.d file named in the format of PRnumber.type. The type can be one of feature, bugfix, removal (also used for deprecations), or misc (for internal-only changes). The content of the file is your changelog entry, which can contain Markdown formatting. Adding credits to the changelog is encouraged, we value your contributions and would like to have you shouted out in the release notes!

For example, a fix in PR #1234 would have its changelog entry in changelog.d/1234.bugfix, and contain content like "The security levels of Florbs are now validated when recieved over federation. Contributed by Jane Matrix".