From 2ab69e081674596352f3fd4a2af874fad9abfdcf Mon Sep 17 00:00:00 2001
From: erikjohnston This document aims to get you started with contributing to Synapse! Everyone is welcome to contribute code to matrix.org
-projects, provided that they are willing to
+ Everyone is welcome to contribute code to Synapse,
+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).Contributing
1. Who can contribute to Synapse?
-
TODO THIS NEEDS UPDATING
If you are running Windows, the Windows Subsystem for Linux (WSL) is strongly recommended for development. More information about WSL can be found at @@ -222,8 +223,8 @@ cp docs/sample_log_config.yaml log_config.yaml
server_name
log_config
to point to the log config you just copiedregistration_shared_secret
so you can use register_new_matrix_user
command.registration_shared_secret
so you can use register_new_matrix_user
command.And then run Synapse with the following command:
poetry run python -m synapse.app.homeserver -c homeserver.yaml
@@ -236,19 +237,19 @@ resolve any issues and re-run until successful.
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
+
Fix your favorite problem or perhaps find a Good First Issue
to work on.
7. Turn coffee into code and documentation!
There is a growing amount of documentation located in the
-docs
-directory, with a rendered version available online.
+docs
+directory, with a rendered version available online.
This documentation is intended primarily for sysadmins running their
own Synapse instance, as well as developers interacting externally with
Synapse.
-docs/development
+docs/development
exists primarily to house documentation for
Synapse developers.
-docs/admin_api
houses documentation
+docs/admin_api
houses documentation
regarding Synapse's Admin API, which is used mostly by sysadmins and external
service developers.
Synapse's code style is documented here. Please follow
@@ -256,12 +257,9 @@ it, including the conventions for build docs
to a book
+build docs
to a book
to check that your contributions render correctly. The docs are written in
GitHub-Flavoured Markdown.
-Some documentation also exists in Synapse's GitHub
-Wiki, although this is primarily
-contributed to by community authors.
When changes are made to any Rust code then you must call either poetry install
or maturin develop
(if installed) to rebuild the Rust code. Using maturin
is quicker than poetry install
, so is recommended when making frequent
@@ -376,7 +374,7 @@ configuration:
To run with Postgres, supply the -e POSTGRES=1 -e MULTI_POSTGRES=1
environment flags.
To run with Synapse in worker mode, supply the -e WORKERS=1 -e REDIS=1
environment flags (in addition to the Postgres flags).
-For more details about other configurations, see the Docker-specific documentation in the SyTest repo.
+For more details about other configurations, see the Docker-specific documentation in the SyTest repo.
Run the integration tests (Complement).
Complement is a suite of black box tests that can be run on any homeserver implementation. It can also be thought of as end-to-end (e2e) tests.
It's often nice to develop on Synapse and write Complement tests at the same time.
@@ -398,7 +396,7 @@ Here is how to run your local Synapse checkout against your local Complement che
If setting WORKERS=1
, optionally set WORKER_TYPES=
to declare which worker
types you wish to test. A simple comma-delimited string containing the worker types
defined from the WORKERS_CONFIG
template in
-here.
+here.
A safe example would be WORKER_TYPES="federation_inbound, federation_sender, synchrotron"
.
See the worker documentation for additional information on workers.
@@ -452,7 +450,7 @@ in the format of PRnumber.type
. The type can be one of the followin
removal
(also used for deprecations)
misc
(for internal-only changes)
-This file will become part of our changelog at the next
+
This file will become part of our changelog at the next
release, so the content of the file should be a short description of your
change in the same style as the rest of the changelog. The file can contain Markdown
formatting, and must end with a full stop (.) or an exclamation mark (!) for
@@ -480,7 +478,7 @@ chicken-and-egg problem.
add the changelog file to your branch, or:
-Look at the list of all
+Look at the list of all
issues/PRs, add one to the
highest number you see, and quickly open the PR before somebody else claims
your number.
diff --git a/develop/development/database_schema.html b/develop/development/database_schema.html
index 62e9dc7257..f2f776ebee 100644
--- a/develop/development/database_schema.html
+++ b/develop/development/database_schema.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/demo.html b/develop/development/demo.html
index 84d8e000a2..886f124ae2 100644
--- a/develop/development/demo.html
+++ b/develop/development/demo.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/dependencies.html b/develop/development/dependencies.html
index 69e1e0db38..03da814adc 100644
--- a/develop/development/dependencies.html
+++ b/develop/development/dependencies.html
@@ -124,10 +124,10 @@
-
+
-
+
@@ -216,9 +216,9 @@ phonenumbers = [
]
We can see this pinned version inside the docker image for that release:
-$ docker pull matrixdotorg/synapse:v1.57.0
+$ docker pull vectorim/synapse:v1.97.0
...
-$ docker run --entrypoint pip matrixdotorg/synapse:v1.57.0 show phonenumbers
+$ docker run --entrypoint pip vectorim/synapse:v1.97.0 show phonenumbers
Name: phonenumbers
Version: 8.12.44
Summary: Python version of Google's common library for parsing, formatting, storing and validating international phone numbers.
diff --git a/develop/development/experimental_features.html b/develop/development/experimental_features.html
index 4df4971891..b46ea01a6d 100644
--- a/develop/development/experimental_features.html
+++ b/develop/development/experimental_features.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/git.html b/develop/development/git.html
index 71ff726695..cd675a4207 100644
--- a/develop/development/git.html
+++ b/develop/development/git.html
@@ -124,10 +124,10 @@
-
+
-
+
@@ -168,10 +168,10 @@ before. Here, by way of an arbitrary example, is the top of git log --grap
Note how the commit comment explains clearly what is changing and why. Also
note the absence of merge commits, as well as the absence of commits called
things like (to pick a few culprits):
-“pep8”, “fix broken
+“pep8”, “fix broken
test”,
-“oops”,
-“typo”, or “Who's
+“oops”,
+“typo”, or “Who's
the president?”.
There are a number of reasons why keeping a clean commit history is a good
thing:
diff --git a/develop/development/internal_documentation/index.html b/develop/development/internal_documentation/index.html
index 23006410f1..e56a6a1682 100644
--- a/develop/development/internal_documentation/index.html
+++ b/develop/development/internal_documentation/index.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/releases.html b/develop/development/releases.html
index 49f83004f2..db1472d3f6 100644
--- a/develop/development/releases.html
+++ b/develop/development/releases.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/reviews.html b/develop/development/reviews.html
index fc6977e379..e78a45369c 100644
--- a/develop/development/reviews.html
+++ b/develop/development/reviews.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/room-dag-concepts.html b/develop/development/room-dag-concepts.html
index 17027019e2..93a6fcd4cb 100644
--- a/develop/development/room-dag-concepts.html
+++ b/develop/development/room-dag-concepts.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/saml.html b/develop/development/saml.html
index b73c73415c..fe9405c747 100644
--- a/develop/development/saml.html
+++ b/develop/development/saml.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/synapse_architecture/cancellation.html b/develop/development/synapse_architecture/cancellation.html
index ed1a616917..5102faf456 100644
--- a/develop/development/synapse_architecture/cancellation.html
+++ b/develop/development/synapse_architecture/cancellation.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/synapse_architecture/faster_joins.html b/develop/development/synapse_architecture/faster_joins.html
index 9948e4a1b8..ce7c0cb5af 100644
--- a/develop/development/synapse_architecture/faster_joins.html
+++ b/develop/development/synapse_architecture/faster_joins.html
@@ -124,10 +124,10 @@
-
+
-
+
diff --git a/develop/development/synapse_architecture/streams.html b/develop/development/synapse_architecture/streams.html
index 46475698b5..485b50dbab 100644
--- a/develop/development/synapse_architecture/streams.html
+++ b/develop/development/synapse_architecture/streams.html
@@ -124,10 +124,10 @@
-
+
-
+
@@ -160,7 +160,7 @@
Streams
-Synapse has a concept of "streams", which are roughly described in id_generators.py
.
+
Synapse has a concept of "streams", which are roughly described in id_generators.py
.
Generally speaking, streams are a series of notifications that something in Synapse's database has changed that the application might need to respond to.
For example:
@@ -168,9 +168,9 @@ For example:
- The account data stream reports changes to users' account data.
- The to-device stream reports when a device has a new to-device message.
-See synapse.replication.tcp.streams
for the full list of streams.
+See synapse.replication.tcp.streams
for the full list of streams.
It is very helpful to understand the streams mechanism when working on any part of Synapse that needs to respond to changes—especially if those changes are made by different workers.
-To that end, let's describe streams formally, paraphrasing from the docstring of AbstractStreamIdGenerator
.
+To that end, let's describe streams formally, paraphrasing from the docstring of AbstractStreamIdGenerator
.
Definition
A stream is an append-only log T1, T2, ..., Tn, ...
of facts1 which grows over time.
Only "writers" can add facts to a stream, and there may be multiple writers.
--
cgit 1.5.1