OpenCloud
/
MatrixSynapse
mirror of https://github.com/matrix-org/synapse
1
0
Fork 0
Code Issues Releases Wiki Activity

Reorganize CONTRIBUTING.md documentation. (#9281)

pull/9425/head
David Teller 2021-02-17 17:23:57 +01:00 committed by GitHub
parent d2f0ec12d5
commit 9e19c6aab4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 190 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

271
CONTRIBUTING.md
View File

@ -1,4 +1,31 @@
# Contributing code to Synapse Welcome to Synapse
This document aims to get you started with contributing to this repo!
- [1. Who can contribute to Synapse?](#1-who-can-contribute-to-synapse)
- [2. What do I need?](#2-what-do-i-need)
- [3. Get the source.](#3-get-the-source)
- [4. Install the dependencies](#4-install-the-dependencies)
* [Under Unix (macOS, Linux, BSD, ...)](#under-unix-macos-linux-bsd-)
* [Under Windows](#under-windows)
- [5. Get in touch.](#5-get-in-touch)
- [6. Pick an issue.](#6-pick-an-issue)
- [7. Turn coffee and documentation into code and documentation!](#7-turn-coffee-and-documentation-into-code-and-documentation)
- [8. Test, test, test!](#8-test-test-test)
* [Run the linters.](#run-the-linters)
* [Run the unit tests.](#run-the-unit-tests)
* [Run the integration tests.](#run-the-integration-tests)
- [9. Submit your patch.](#9-submit-your-patch)
* [Changelog](#changelog)
+ [How do I know what to call the changelog file before I create the PR?](#how-do-i-know-what-to-call-the-changelog-file-before-i-create-the-pr)
+ [Debian changelog](#debian-changelog)
* [Sign off](#sign-off)
- [10. Turn feedback into better code.](#10-turn-feedback-into-better-code)
- [11. Find a new issue.](#11-find-a-new-issue)
- [Notes for maintainers on merging PRs etc](#notes-for-maintainers-on-merging-prs-etc)
- [Conclusion](#conclusion)
# 1. Who can contribute to Synapse?
Everyone is welcome to contribute code to [matrix.org Everyone is welcome to contribute code to [matrix.org
projects](https://github.com/matrix-org), provided that they are willing to projects](https://github.com/matrix-org), provided that they are willing to
@ -9,70 +36,179 @@ 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 - in our case, this is almost always Apache Software License v2 (see
[LICENSE](LICENSE)). [LICENSE](LICENSE)).
## How to contribute # 2. What do I need?
The code of Synapse is written in Python 3. To do pretty much anything, you'll need [a recent version of Python 3](https://wiki.python.org/moin/BeginnersGuide/Download).
The source code of Synapse is hosted on GitHub. You will also need [a recent version of git](https://github.com/git-guides/install-git).
For some tests, you will need [a recent version of Docker](https://docs.docker.com/get-docker/).
# 3. Get the source.
The preferred and easiest way to contribute changes is to fork the relevant The preferred and easiest way to contribute changes is to fork the relevant
project on github, and then [create a pull request]( project on GitHub, and then [create a pull request](
https://help.github.com/articles/using-pull-requests/) to ask us to pull your https://help.github.com/articles/using-pull-requests/) to ask us to pull your
changes into our repo. changes into our repo.
Some other points to follow: Please base your changes on the `develop` branch.
* Please base your changes on the `develop` branch. ```sh
git clone git@github.com:YOUR_GITHUB_USER_NAME/synapse.git
git checkout develop
```
* Please follow the [code style requirements](#code-style). If you need help getting started with git, this is beyond the scope of the document, but you
can find many good git tutorials on the web.
* Please include a [changelog entry](#changelog) with each PR. # 4. Install the dependencies
* Please [sign off](#sign-off) your contribution. ## Under Unix (macOS, Linux, BSD, ...)
* Please keep an eye on the pull request for feedback from the [continuous Once you have installed Python 3 and added the source, please open a terminal and
integration system](#continuous-integration-and-testing) and try to fix any setup a *virtualenv*, as follows:
errors that come up.
* If you need to [update your PR](#updating-your-pull-request), just add new ```sh
commits to your branch rather than rebasing. cd path/where/you/have/cloned/the/repository
python3 -m venv ./env
source ./env/bin/activate
pip install -e ".[all,lint,mypy,test]"
pip install tox
```
## Code style This will install the developer dependencies for the project.
## Under Windows
TBD
# 5. Get in touch.
Join our developer community on Matrix: #synapse-dev:matrix.org !
# 6. Pick an issue.
Fix your favorite problem or perhaps find a [Good First Issue](https://github.com/matrix-org/synapse/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22)
to work on.
# 7. Turn coffee and documentation into code and documentation!
Synapse's code style is documented [here](docs/code_style.md). Please follow Synapse's code style is documented [here](docs/code_style.md). Please follow
it, including the conventions for the [sample configuration it, including the conventions for the [sample configuration
file](docs/code_style.md#configuration-file-format). file](docs/code_style.md#configuration-file-format).
Many of the conventions are enforced by scripts which are run as part of the There is a growing amount of documentation located in the [docs](docs)
[continuous integration system](#continuous-integration-and-testing). To help directory. This documentation is intended primarily for sysadmins running their
check if you have followed the code style, you can run `scripts-dev/lint.sh` own Synapse instance, as well as developers interacting externally with
locally. You'll need python 3.6 or later, and to install a number of tools: Synapse. [docs/dev](docs/dev) exists primarily to house documentation for
Synapse developers. [docs/admin_api](docs/admin_api) houses documentation
regarding Synapse's Admin API, which is used mostly by sysadmins and external
service developers.
``` If you add new files added to either of these folders, please use [GitHub-Flavoured
# Install the dependencies Markdown](https://guides.github.com/features/mastering-markdown/).
pip install -e ".[lint,mypy]"
# Run the linter script Some documentation also exists in [Synapse's GitHub
Wiki](https://github.com/matrix-org/synapse/wiki), although this is primarily
contributed to by community authors.
# 8. Test, test, test!
<a name="test-test-test"></a>
While you're developing and before submitting a patch, you'll
want to test your code.
## Run the linters.
The linters look at your code and do two things:
- ensure that your code follows the coding style adopted by the project;
- catch a number of errors in your code.
They're pretty fast, don't hesitate!
```sh
source ./env/bin/activate
./scripts-dev/lint.sh ./scripts-dev/lint.sh
``` ```
**Note that the script does not just test/check, but also reformats code, so you Note that this script *will modify your files* to fix styling errors.
may wish to ensure any new code is committed first**. Make sure that you have saved all your files.
By default, this script checks all files and can take some time; if you alter If you wish to restrict the linters to only the files changed since the last commit
only certain files, you might wish to specify paths as arguments to reduce the (much faster!), you can instead run:
run-time:
```sh
source ./env/bin/activate
./scripts-dev/lint.sh -d
``` ```
Or if you know exactly which files you wish to lint, you can instead run:
```sh
source ./env/bin/activate
./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder ./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
``` ```
You can also provide the `-d` option, which will lint the files that have been ## Run the unit tests.
changed since the last git commit. This will often be significantly faster than
linting the whole codebase.
Before pushing new changes, ensure they don't produce linting errors. Commit any The unit tests run parts of Synapse, including your changes, to see if anything
files that were corrected. was broken. They are slower than the linters but will typically catch more errors.
```sh
source ./env/bin/activate
trial tests
```
If you wish to only run *some* unit tests, you may specify
another module instead of `tests` - or a test class or a method:
```sh
source ./env/bin/activate
trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
```
If your tests fail, you may wish to look at the logs:
```sh
less _trial_temp/test.log
```
## Run the integration tests.
The integration tests are a more comprehensive suite of tests. They
run a full version of Synapse, including your changes, to check if
anything was broken. They are slower than the unit tests but will
typically catch more errors.
The following command will let you run the integration test with the most common
configuration:
```sh
$ docker run --rm -it -v /path/where/you/have/cloned/the/repository\:/src:ro -v /path/to/where/you/want/logs\:/logs matrixdotorg/sytest-synapse:py37
```
This configuration should generally cover your needs. For more details about other configurations, see [documentation in the SyTest repo](https://github.com/matrix-org/sytest/blob/develop/docker/README.md).
# 9. Submit your patch.
Once you're happy with your patch, it's time to prepare a Pull Request.
To prepare a Pull Request, please:
1. verify that [all the tests pass](#test-test-test), including the coding style;
2. [sign off](#sign-off) your contribution;
3. `git push` your commit to your fork of Synapse;
4. on GitHub, [create the Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request);
5. add a [changelog entry](#changelog) and push it to your Pull Request;
6. for most contributors, that's all - however, if you are a member of the organization `matrix-org`, on GitHub, please request a review from `matrix.org / Synapse Core`.
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 ## Changelog
@ -156,24 +292,6 @@ directory, you will need both a regular newsfragment *and* an entry in the
debian changelog. (Though typically such changes should be submitted as two debian changelog. (Though typically such changes should be submitted as two
separate pull requests.) separate pull requests.)
## Documentation
There is a growing amount of documentation located in the [docs](docs)
directory. This documentation is intended primarily for sysadmins running their
own Synapse instance, as well as developers interacting externally with
Synapse. [docs/dev](docs/dev) exists primarily to house documentation for
Synapse developers. [docs/admin_api](docs/admin_api) houses documentation
regarding Synapse's Admin API, which is used mostly by sysadmins and external
service developers.
New files added to both folders should be written in [Github-Flavoured
Markdown](https://guides.github.com/features/mastering-markdown/), and attempts
should be made to migrate existing documents to markdown where possible.
Some documentation also exists in [Synapse's Github
Wiki](https://github.com/matrix-org/synapse/wiki), although this is primarily
contributed to by community authors.
## Sign off ## Sign off
In order to have a concrete record that your contribution is intentional In order to have a concrete record that your contribution is intentional
@ -240,47 +358,36 @@ Git allows you to add this signoff automatically when using the `-s`
flag to `git commit`, which uses the name and email set in your flag to `git commit`, which uses the name and email set in your
`user.name` and `user.email` git configs. `user.name` and `user.email` git configs.
## Continuous integration and testing
[Buildkite](https://buildkite.com/matrix-dot-org/synapse) will automatically # 10. Turn feedback into better code.
run a series of checks and tests against any PR which is opened against the
project; if your change breaks the build, this will be shown in GitHub, with
links to the build results. If your build fails, please try to fix the errors
and update your branch.
To run unit tests in a local development environment, you can use: Once the Pull Request is opened, you will see a few things:
- ``tox -e py35`` (requires tox to be installed by ``pip install tox``) 1. our automated CI (Continuous Integration) pipeline will run (again) the linters, the unit tests, the integration tests and more;
for SQLite-backed Synapse on Python 3.5. 2. one or more of the developers will take a look at your Pull Request and offer feedback.
- ``tox -e py36`` for SQLite-backed Synapse on Python 3.6.
- ``tox -e py36-postgres`` for PostgreSQL-backed Synapse on Python 3.6
(requires a running local PostgreSQL with access to create databases).
- ``./test_postgresql.sh`` for PostgreSQL-backed Synapse on Python 3.5
(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, From this point, you should:
see the [documentation in the SyTest repo](
https://github.com/matrix-org/sytest/blob/develop/docker/README.md) for more
information.
## Updating your pull request 1. Look at the results of the CI pipeline.
- If there is any error, fix the error.
2. If a developer has requested changes, make these changes and let us know if it is ready for a developer to review again.
3. Create a new commit with the changes.
- Please do NOT overwrite the history. New commits make the reviewer's life easier.
- Push this commits to your Pull Request.
4. Back to 1.
If you decide to make changes to your pull request - perhaps to address issues Once both the CI and the developers are happy, the patch will be merged into Synapse and released shortly!
raised in a review, or to fix problems highlighted by [continuous
integration](#continuous-integration-and-testing) - just add new commits to your
branch, and push to GitHub. The pull request will automatically be updated.
Please **avoid** rebasing your branch, especially once the PR has been # 11. Find a new issue.
reviewed: doing so makes it very difficult for a reviewer to see what has
changed since a previous review.
## Notes for maintainers on merging PRs etc By now, you know the drill!
# Notes for maintainers on merging PRs etc
There are some notes for those with commit access to the project on how we There are some notes for those with commit access to the project on how we
manage git [here](docs/dev/git.md). manage git [here](docs/dev/git.md).
## Conclusion # Conclusion
That's it! Matrix is a very open and collaborative project as you might expect That's it! Matrix is a very open and collaborative project as you might expect
given our obsession with open communication. If we're going to successfully given our obsession with open communication. If we're going to successfully

1
changelog.d/9281.doc Normal file
View File

@ -0,0 +1 @@
Reorganizing CHANGELOG.md.