Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Reorganize CONTRIBUTING.md #9281

Merged
merged 8 commits into from
Feb 17, 2021
Merged

Reorganize CONTRIBUTING.md #9281

Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1b4ef44
Rewriting CONTRIBUTING.md
Yoric Feb 1, 2021
2371f50
FIXUP: CONTRIBUTING.md
Yoric Feb 8, 2021
a54ed96
FIXUP: Applying feedback
Yoric Feb 11, 2021
c9f9d7c
FIXUP: ToC
Yoric Feb 11, 2021
ad05f99
FIXUP: Applied feedback
Yoric Feb 11, 2021
01271f2
Fix broken links.
clokep Feb 17, 2021
e1b45a5
Fix broken formatting.
clokep Feb 17, 2021
72993d3
Clarify what to do after making changes.
clokep Feb 17, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 46 additions & 41 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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---)
clokep marked this conversation as resolved.
Show resolved Hide resolved
* [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-)
clokep marked this conversation as resolved.
Show resolved Hide resolved
* [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-)
clokep marked this conversation as resolved.
Show resolved Hide resolved
+ [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
Expand All @@ -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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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, open a terminal and set up a virtualenv. For example:

Yoric marked this conversation as resolved.
Show resolved Hide resolved

```sh
mkdir -p ~/synapse
cd WHERE_YOU_HAVE_CLONED_THE_REPOSITORY
python3 -m venv ./env
source ./env/bin/activate
Yoric marked this conversation as resolved.
Show resolved Hide resolved
pip install -e ".[all,lint,mypy,test]"
Expand All @@ -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
Expand All @@ -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!
<a name="test-test-test"></a>

While you're developing and before submitting a patch, you'll
Expand All @@ -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
Expand Down Expand Up @@ -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`;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally we'll do this internally once we've done a first pass of triage.

Suggested change
6. on Github, request review from `matrix.org / Synapse Core`;

(I'm not entirely sure it's even possible for people outside the organisation)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, it's still information that it took me 2 months to find so I'll try and find a way to mention it :)



## Changelog

Expand Down Expand Up @@ -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:

Expand All @@ -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.
clokep marked this conversation as resolved.
Show resolved Hide resolved
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!

Expand Down