From 1b4ef4417ea1d3e8aa9f84d372dd8c6ee326c813 Mon Sep 17 00:00:00 2001 From: David Teller Date: Mon, 1 Feb 2021 10:21:12 +0100 Subject: [PATCH 1/8] Rewriting CONTRIBUTING.md Signed-off-by: Your Name --- CONTRIBUTING.md | 257 +++++++++++++++++++++++++++++-------------- changelog.d/9281.doc | 1 + 2 files changed, 176 insertions(+), 82 deletions(-) create mode 100644 changelog.d/9281.doc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d7bb8f969cf..668ca1ca0807 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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-) + * [Under Unix (macOS, Linux, BSD, ...)](#under-unix--macos--linux--bsd---) + * [Under Windows](#under-windows) +- [3. Get the source.](#3-get-the-source) +- [4. Get in touch.](#4-get-in-touch) +- [5. Pick an issue.](#5-pick-an-issue) +- [6. Turn coffee and documentation into code and documentation!](#6-turn-coffee-and-documentation-into-code-and-documentation-) +- [7. Test, test, test!](#7-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) +- [8. Submit your patch.](#8-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) +- [9. Turn feedback into better code.](#9-turn-feedback-into-better-code) +- [10. Find a new issue.](#10-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 projects](https://github.com/matrix-org), provided that they are willing to @@ -9,70 +36,163 @@ 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](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/). + +## Under Unix (macOS, Linux, BSD, ...) + +Once you have installed Python 3, please open a Terminal and run: + +```sh +mkdir -p ~/synapse +python3 -m venv ./env +source ./env/bin/activate +pip install -e ".[all,lint,mypy,test,black,tox]" +``` + +This will install the developer dependencies for the project. + +## Under Windows + +TBD + + +# 3. Get the source. The preferred and easiest way to contribute changes is to fork the relevant project on github, and then [create a pull request]( https://help.github.com/articles/using-pull-requests/) to ask us to pull your changes into our repo. -Some other points to follow: +Please base your changes on the `develop` branch. + +```sh +git clone git@github.com:matrix-org/synapse.git +``` - * Please base your changes on the `develop` branch. +# 4. Get in touch. - * Please follow the [code style requirements](#code-style). +Join our developer community on Matrix: #synapse-dev:matrix.org ! - * Please include a [changelog entry](#changelog) with each PR. - * Please [sign off](#sign-off) your contribution. +# 5. Pick an issue. - * Please keep an eye on the pull request for feedback from the [continuous - integration system](#continuous-integration-and-testing) and try to fix any - errors that come up. +Fix your favorite problem of find an issue on https://github.com/matrix-org/synapse/issues/ . - * If you need to [update your PR](#updating-your-pull-request), just add new - commits to your branch rather than rebasing. -## Code style +# 6. Turn coffee and documentation into code and documentation! Synapse's code style is documented [here](docs/code_style.md). Please follow it, including the conventions for the [sample configuration file](docs/code_style.md#configuration-file-format). -Many of the conventions are enforced by scripts which are run as part of the -[continuous integration system](#continuous-integration-and-testing). To help -check if you have followed the code style, you can run `scripts-dev/lint.sh` -locally. You'll need python 3.6 or later, and to install a number of tools: +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. + +If you add new files added to either of these folders, please use [Github-Flavoured +Markdown](https://guides.github.com/features/mastering-markdown/). + +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. -``` -# Install the dependencies -pip install -e ".[lint,mypy]" -# Run the linter script +# 7. Test, test, test! + + +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 very fast, don't hesitate! + +```sh +source ./env/bin/activate ./scripts-dev/lint.sh ``` -**Note that the script does not just test/check, but also reformats code, so you -may wish to ensure any new code is committed first**. +Note that the linters *will modify your files* to fix styling errors. +Make sure that you have saved all your files. -By default, this script checks all files and can take some time; if you alter -only certain files, you might wish to specify paths as arguments to reduce the -run-time: -``` +If you wish to restrict the linters to only run on some files, you can instead run: + +```sh +source ./env/bin/activate ./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 -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 -files that were corrected. +## Run the unit tests. + +The unit tests run parts of Synapse, including your changes, to see if anything +was broken. They are slower than the linters but will typically catch more errors. + +```sh +source ./env/bin/activate +python -m twisted.trial tests +``` + +If you wish to only run *some* unit tests, you may specify +another module instead of `tests`: + +```sh +source ./env/bin/activate +python -m twisted.trial tests.rest.admin.test_room +``` + +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 run the full Synapse, including your changes, to +see if anything was broken. They are slower than the unit tests but will +typically catch more errors. + + +The following will run the test suite using postgres. You will need [Docker](https://docs.docker.com/get-docker/) installed. + +```sh +./test_postgresql.sh +``` + +Or, if you prefer running the same tests without postgres or Docker, use this command. + +```sh +tox -e py36 +``` + +# 8. Submit your patch. + +Once you're happy with your patch, it's time to prepare a Pull Request. + +To prepare a Pull Request, please: -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. +1. verify that [all the tests pass](#test-test-test), including the coding style; +2. add a [changelog entry](#changelog); +3. [sign off](#sign-off) your contribution; +4. on Github, [create the Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request); +5. on Github, request review from `matrix.org / Synapse Core`. ## Changelog @@ -156,24 +276,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 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 In order to have a concrete record that your contribution is intentional @@ -240,47 +342,38 @@ 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 `user.name` and `user.email` git configs. -## Continuous integration and testing -[Buildkite](https://buildkite.com/matrix-dot-org/synapse) will automatically -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. +# 9. Turn feedback into better code. + +Once the Pull Request is opened, you will see a few things: + +1. our automated CI (Continuous Integration) pipeline will run (again) the linters, the unit tests, the integration tests and more; +2. one or more of the developers will take a look at your Pull Request and offer feedback. -To run unit tests in a local development environment, you can use: +From this point, you should: -- ``tox -e py35`` (requires tox to be installed by ``pip install tox``) - for SQLite-backed Synapse on Python 3.5. -- ``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. +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. +3. Create a new patch with the changes. + - Please do NOT overwrite the history. New patches make the reviewer's life easier. + - Push this patch to your Pull Request. +4. Back to 1. -Docker images are available for running the integration tests (SyTest) locally, -see the [documentation in the SyTest repo]( -https://github.com/matrix-org/sytest/blob/develop/docker/README.md) for more -information. +If the CI pipeline detects errors, please fix them. If the developers suggest change, please fix them, too. -## Updating your pull request +Once both the CI and the developers are happy, the patch will be merged into Synapse and released shortly! -If you decide to make changes to your pull request - perhaps to address issues -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. +# 10. Find a new issue. -Please **avoid** rebasing your branch, especially once the PR has been -reviewed: doing so makes it very difficult for a reviewer to see what has -changed since a previous review. +By now, you know the drill! -## Notes for maintainers on merging PRs etc +# Notes for maintainers on merging PRs etc There are some notes for those with commit access to the project on how we manage git [here](docs/dev/git.md). -## Conclusion +# Conclusion 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 diff --git a/changelog.d/9281.doc b/changelog.d/9281.doc new file mode 100644 index 000000000000..4dea375f8001 --- /dev/null +++ b/changelog.d/9281.doc @@ -0,0 +1 @@ +Reorganizing CHANGELOG.md. \ No newline at end of file From 2371f50cb754097108bcf3de0e5f407744e3c01c Mon Sep 17 00:00:00 2001 From: David Teller Date: Mon, 8 Feb 2021 10:52:03 +0100 Subject: [PATCH 2/8] FIXUP: CONTRIBUTING.md --- CONTRIBUTING.md | 62 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 42 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 668ca1ca0807..bd7af5192f50 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,7 +52,8 @@ Once you have installed Python 3, please open a Terminal and run: mkdir -p ~/synapse python3 -m venv ./env source ./env/bin/activate -pip install -e ".[all,lint,mypy,test,black,tox]" +pip install -e ".[all,lint,mypy,test]" +pip install tox ``` This will install the developer dependencies for the project. @@ -72,7 +73,7 @@ changes into our repo. Please base your changes on the `develop` branch. ```sh -git clone git@github.com:matrix-org/synapse.git +git clone git@github.com:YOUR_GITHUB_USER_NAME/synapse.git ``` # 4. Get in touch. @@ -82,7 +83,8 @@ Join our developer community on Matrix: #synapse-dev:matrix.org ! # 5. Pick an issue. -Fix your favorite problem of find an issue on https://github.com/matrix-org/synapse/issues/ . +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. # 6. Turn coffee and documentation into code and documentation! @@ -120,7 +122,7 @@ 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 very fast, don't hesitate! +They're pretty fast, don't hesitate! ```sh source ./env/bin/activate @@ -130,15 +132,21 @@ source ./env/bin/activate Note that the linters *will modify your files* to fix styling errors. Make sure that you have saved all your files. +If you wish to restrict the linters to only the files changed since the last commit +(much faster!), you can instead run: -If you wish to restrict the linters to only run on some files, you can instead run: +```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 ``` - ## Run the unit tests. The unit tests run parts of Synapse, including your changes, to see if anything @@ -150,11 +158,11 @@ python -m twisted.trial tests ``` If you wish to only run *some* unit tests, you may specify -another module instead of `tests`: +another module instead of `tests` - or a test class or a method: ```sh source ./env/bin/activate -python -m twisted.trial tests.rest.admin.test_room +python -m twisted.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: @@ -165,23 +173,35 @@ less _trial_temp/test.log ## Run the integration tests. -The integration tests run the full Synapse, including your changes, to +The integration tests run a full Synapse, including your changes, to see if anything was broken. They are slower than the unit tests but will typically catch more errors. +To run the entire test suite using Sqlite3, use the following command: -The following will run the test suite using postgres. You will need [Docker](https://docs.docker.com/get-docker/) installed. +```sh +source ./env/bin/activate +tox -e py36 +``` + +If you wish to only run *some* integration tests, you may +similarly specify a module, e.g.: ```sh -./test_postgresql.sh +source ./env/bin/activate +tox -e py36 -- test.rest.admin.test_room ``` -Or, if you prefer running the same tests without postgres or Docker, use this command. + + +Or, to run the test suite using postgres, use the following command. You will need [Docker](https://docs.docker.com/get-docker/) installed. ```sh -tox -e py36 +source ./env/bin/activate +./test_postgresql.sh ``` + # 8. Submit your patch. Once you're happy with your patch, it's time to prepare a Pull Request. @@ -191,8 +211,12 @@ To prepare a Pull Request, please: 1. verify that [all the tests pass](#test-test-test), including the coding style; 2. add a [changelog entry](#changelog); 3. [sign off](#sign-off) your contribution; -4. on Github, [create the Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request); -5. on Github, request review from `matrix.org / Synapse Core`. +4. Push code to commits to your fork of Synapse: +```sh +git push origin develop +``` +5. on Github, [create the Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request); +6. on Github, request review from `matrix.org / Synapse Core`. ## Changelog @@ -355,13 +379,11 @@ From this point, you should: 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. -3. Create a new patch with the changes. - - Please do NOT overwrite the history. New patches make the reviewer's life easier. - - Push this patch to your Pull Request. +3. Create a new commit with the changes. + - Please [do NOT overwrite the history](docs/dev/git.md#on-keeping-the-commit-history-clean). New commits make the reviewer's life easier. + - Push this commits to your Pull Request. 4. Back to 1. -If the CI pipeline detects errors, please fix them. If the developers suggest change, please fix them, too. - Once both the CI and the developers are happy, the patch will be merged into Synapse and released shortly! # 10. Find a new issue. From a54ed96b7af5658ace926bd36b3904e537dd3977 Mon Sep 17 00:00:00 2001 From: David Teller Date: Thu, 11 Feb 2021 08:23:34 +0100 Subject: [PATCH 3/8] FIXUP: Applying feedback --- CONTRIBUTING.md | 69 ++++++++++++++++++++++++++----------------------- 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd7af5192f50..a45efb6e8abc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,12 +44,32 @@ The source code of Synapse is hosted on Github. You will also need [a recent ver 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 +project on github, and then [create a pull request]( +https://help.github.com/articles/using-pull-requests/) to ask us to pull your +changes into our repo. + +Please base your changes on the `develop` branch. + +```sh +git clone git@github.com:YOUR_GITHUB_USER_NAME/synapse.git +git checkout develop +``` + +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. + +# 4. Install the dependencies + ## Under Unix (macOS, Linux, BSD, ...) -Once you have installed Python 3, please open a Terminal and run: +Once you have installed Python 3 and added the source, please open a Terminal and run: ```sh -mkdir -p ~/synapse +cd WHERE_YOU_HAVE_CLONED_THE_REPOSITORY python3 -m venv ./env source ./env/bin/activate pip install -e ".[all,lint,mypy,test]" @@ -63,31 +83,18 @@ This will install the developer dependencies for the project. TBD -# 3. Get the source. - -The preferred and easiest way to contribute changes is to fork the relevant -project on github, and then [create a pull request]( -https://help.github.com/articles/using-pull-requests/) to ask us to pull your -changes into our repo. - -Please base your changes on the `develop` branch. - -```sh -git clone git@github.com:YOUR_GITHUB_USER_NAME/synapse.git -``` - -# 4. Get in touch. +# 5. Get in touch. Join our developer community on Matrix: #synapse-dev:matrix.org ! -# 5. Pick an issue. +# 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. -# 6. Turn coffee and documentation into code and documentation! +# 7. Turn coffee and documentation into code and documentation! Synapse's code style is documented [here](docs/code_style.md). Please follow it, including the conventions for the [sample configuration @@ -109,7 +116,7 @@ Wiki](https://github.com/matrix-org/synapse/wiki), although this is primarily contributed to by community authors. -# 7. Test, test, test! +# 8. Test, test, test! While you're developing and before submitting a patch, you'll @@ -129,7 +136,7 @@ source ./env/bin/activate ./scripts-dev/lint.sh ``` -Note that the linters *will modify your files* to fix styling errors. +Note that this script *will modify your files* to fix styling errors. Make sure that you have saved all your files. If you wish to restrict the linters to only the files changed since the last commit @@ -202,21 +209,19 @@ source ./env/bin/activate ``` -# 8. Submit your patch. +# 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. add a [changelog entry](#changelog); -3. [sign off](#sign-off) your contribution; -4. Push code to commits to your fork of Synapse: -```sh -git push origin develop -``` -5. on Github, [create the Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request); -6. on Github, request review from `matrix.org / Synapse Core`. +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. on Github, request review from `matrix.org / Synapse Core`; + ## Changelog @@ -367,7 +372,7 @@ flag to `git commit`, which uses the name and email set in your `user.name` and `user.email` git configs. -# 9. Turn feedback into better code. +# 10. Turn feedback into better code. Once the Pull Request is opened, you will see a few things: @@ -380,13 +385,13 @@ From this point, you should: - If there is any error, fix the error. 2. If a developer has requested changes, make these changes. 3. Create a new commit with the changes. - - Please [do NOT overwrite the history](docs/dev/git.md#on-keeping-the-commit-history-clean). New commits make the reviewer's life easier. + - 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. Once both the CI and the developers are happy, the patch will be merged into Synapse and released shortly! -# 10. Find a new issue. +# 11. Find a new issue. By now, you know the drill! From c9f9d7c1786bcb53c6ea405939fbe2dfcfb38b45 Mon Sep 17 00:00:00 2001 From: David Teller Date: Thu, 11 Feb 2021 10:25:32 +0100 Subject: [PATCH 4/8] FIXUP: ToC --- CONTRIBUTING.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a45efb6e8abc..f99b529e5272 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,27 +4,27 @@ 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) -- [3. Get the source.](#3-get-the-source) -- [4. Get in touch.](#4-get-in-touch) -- [5. Pick an issue.](#5-pick-an-issue) -- [6. Turn coffee and documentation into code and documentation!](#6-turn-coffee-and-documentation-into-code-and-documentation-) -- [7. Test, test, test!](#7-test--test--test-) +- [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) -- [8. Submit your patch.](#8-submit-your-patch) +- [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) -- [9. Turn feedback into better code.](#9-turn-feedback-into-better-code) -- [10. Find a new issue.](#10-find-a-new-issue) +- [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 From ad05f997240570d3e697acbfa84c9b4e73133ce5 Mon Sep 17 00:00:00 2001 From: David Teller Date: Thu, 11 Feb 2021 17:38:29 +0100 Subject: [PATCH 5/8] FIXUP: Applied feedback --- CONTRIBUTING.md | 49 ++++++++++++++++++------------------------------- 1 file changed, 18 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f99b529e5272..fdfeec3621bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,7 +40,7 @@ license - in our case, this is almost always Apache Software License v2 (see 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). +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/). @@ -48,7 +48,7 @@ For some tests, you will need [a recent version of Docker](https://docs.docker.c # 3. Get the source. 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 changes into our repo. @@ -66,10 +66,11 @@ can find many good git tutorials on the web. ## Under Unix (macOS, Linux, BSD, ...) -Once you have installed Python 3 and added the source, please open a Terminal and run: +Once you have installed Python 3 and added the source, please open a terminal and +setup a *virtualenv*, as follows: ```sh -cd WHERE_YOU_HAVE_CLONED_THE_REPOSITORY +cd path/where/you/have/cloned/the/repository python3 -m venv ./env source ./env/bin/activate pip install -e ".[all,lint,mypy,test]" @@ -108,10 +109,10 @@ 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 +If you add new files added to either of these folders, please use [GitHub-Flavoured Markdown](https://guides.github.com/features/mastering-markdown/). -Some documentation also exists in [Synapse's Github +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. @@ -161,7 +162,7 @@ was broken. They are slower than the linters but will typically catch more error ```sh source ./env/bin/activate -python -m twisted.trial tests +trial tests ``` If you wish to only run *some* unit tests, you may specify @@ -169,7 +170,7 @@ another module instead of `tests` - or a test class or a method: ```sh source ./env/bin/activate -python -m twisted.trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite +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: @@ -180,33 +181,19 @@ less _trial_temp/test.log ## Run the integration tests. -The integration tests run a full Synapse, including your changes, to -see if anything was broken. They are slower than the unit tests but will +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. -To run the entire test suite using Sqlite3, use the following command: +The following command will let you run the integration test with the most common +configuration: ```sh -source ./env/bin/activate -tox -e py36 -``` - -If you wish to only run *some* integration tests, you may -similarly specify a module, e.g.: - -```sh -source ./env/bin/activate -tox -e py36 -- test.rest.admin.test_room +$ 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 ``` - - -Or, to run the test suite using postgres, use the following command. You will need [Docker](https://docs.docker.com/get-docker/) installed. - -```sh -source ./env/bin/activate -./test_postgresql.sh -``` +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. @@ -218,9 +205,9 @@ 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); +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. on Github, request review from `matrix.org / Synapse Core`; +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`. ## Changelog From 01271f21d6bc3e596c9baf46b3acb0b3b201a286 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 17 Feb 2021 10:53:13 -0500 Subject: [PATCH 6/8] Fix broken links. --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fdfeec3621bd..fb3a667f519e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,22 +2,22 @@ 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-) +- [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 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-) +- [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-) + + [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) From e1b45a5e3e2b5b3c48b3590f385cc5dd914f5950 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 17 Feb 2021 10:53:32 -0500 Subject: [PATCH 7/8] Fix broken formatting. --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb3a667f519e..db4706e1e4fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -369,11 +369,11 @@ Once the Pull Request is opened, you will see a few things: From this point, you should: 1. Look at the results of the CI pipeline. - - If there is any error, fix the error. + - If there is any error, fix the error. 2. If a developer has requested changes, make these changes. 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. + - 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. Once both the CI and the developers are happy, the patch will be merged into Synapse and released shortly! From 72993d350461b5e9eba3b9cfda5eb33ebea27942 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 17 Feb 2021 10:53:45 -0500 Subject: [PATCH 8/8] Clarify what to do after making changes. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db4706e1e4fe..b6a70f7ffed4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -370,7 +370,7 @@ From this point, you should: 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. +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.