From 2ab69e081674596352f3fd4a2af874fad9abfdcf Mon Sep 17 00:00:00 2001 From: erikjohnston Date: Wed, 13 Dec 2023 15:42:43 +0000 Subject: deploy: 8613f7693ea284a023dc625c9a35b9ff482f5fd0 --- develop/development/cas.html | 4 +-- develop/development/contributing_guide.html | 38 ++++++++++------------ develop/development/database_schema.html | 4 +-- develop/development/demo.html | 4 +-- develop/development/dependencies.html | 8 ++--- develop/development/experimental_features.html | 4 +-- develop/development/git.html | 10 +++--- .../development/internal_documentation/index.html | 4 +-- develop/development/releases.html | 4 +-- develop/development/reviews.html | 4 +-- develop/development/room-dag-concepts.html | 4 +-- develop/development/saml.html | 4 +-- .../synapse_architecture/cancellation.html | 4 +-- .../synapse_architecture/faster_joins.html | 4 +-- .../development/synapse_architecture/streams.html | 10 +++--- 15 files changed, 54 insertions(+), 56 deletions(-) (limited to 'develop/development') diff --git a/develop/development/cas.html b/develop/development/cas.html index 09ffd57cf1..d2936b41e6 100644 --- a/develop/development/cas.html +++ b/develop/development/cas.html @@ -124,10 +124,10 @@ - + - + diff --git a/develop/development/contributing_guide.html b/develop/development/contributing_guide.html index 6975222cb4..29eee06328 100644 --- a/develop/development/contributing_guide.html +++ b/develop/development/contributing_guide.html @@ -124,10 +124,10 @@ - + - + @@ -162,14 +162,15 @@

Contributing

This document aims to get you started with contributing to Synapse!

1. Who can contribute 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).

+LICENSE).

+

TODO THIS NEEDS UPDATING

2. What do I need?

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

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