mirrors/dendrite
1
0
Fork 0
mirror of https://github.com/matrix-org/dendrite.git synced 2026-01-04 20:53:09 -06:00
Code Issues Packages Projects Releases Wiki Activity

More updates

Browse source
This commit is contained in:
Neil Alexander 2022-05-11 12:42:03 +01:00
parent e225399fbd
commit af9190574e
No known key found for this signature in database
GPG key ID: A02A2019A2BB0944
5 changed files with 89 additions and 126 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

101
docs/CONTRIBUTING.md
View file

@ -9,47 +9,89 @@ permalink: /development/contributing
Everyone is welcome to contribute to Dendrite! We aim to make it as easy as
possible to get started.
Please ensure that you sign off your contributions! See [Sign Off](#sign-off)
section below.
## Sign off
We ask that everyone who contributes to the project signs off their contributions
in accordance with the [DCO](https://github.com/matrix-org/matrix-spec/blob/main/CONTRIBUTING.rst#sign-off).
In effect, this means adding a statement to your pull requests or commit messages
along the lines of:
```
Signed-off-by: Full Name <email address>
```
Unfortunately we can't accept contributions without it.
## Getting up and running
See [INSTALL.md](INSTALL.md) for instructions on setting up a running dev
instance of dendrite, and [CODE_STYLE.md](CODE_STYLE.md) for the code style
guide.
See the [Installation](INSTALL.md) section for information on how to build an
instance of Dendrite. You will likely need this in order to test your changes.
We use [golangci-lint](https://github.com/golangci/golangci-lint) to lint
Dendrite which can be executed via:
## Code style
```
On the whole, the format as prescribed by `gofmt`, `goimports` etc. is exactly
what we use and expect. Please make sure that you run one of these formatters before
submitting your contribution.
## Comments
Please make sure that the comments adequately explain *why* your code does what it
does. If there are statements that are not obvious, please comment what they do.
We also have some special tags which we use for searchability. These are:
* `// TODO:` for places where a future review, rewrite or refactor is likely required
* `// FIXME:` for places where we know there is an outstanding bug that needs a fix
* `// NOTSPEC:` for places where the behaviour specifically does not match what the
[Matrix Specification](https://spec.matrix.org/) prescribes, along with a description
of *why* that is the case.
## Linting
We use [golangci-lint](https://github.com/golangci/golangci-lint) to lint Dendrite
which can be executed via:
```bash
golangci-lint run
```
If you are receiving linter warnings that you are certain are spurious and want to
silence them, you can annotate the relevant lines or methods with a `// nolint:`
comment. Please avoid doing this if you can.
## Unit tests
We also have unit tests which we run via:
```
```bash
go test ./...
```
## Continuous Integration
In general, we like submissions that come with tests. Anything that proves that the
code is functioning as intended is great, and to ensure that we will find out quickly
in the future if any regressions happen.
When a Pull Request is submitted, continuous integration jobs are run
automatically to ensure the code builds and is relatively well-written. The jobs
are run on [Buildkite](https://buildkite.com/matrix-dot-org/dendrite/), and the
Buildkite pipeline configuration can be found in Matrix.org's [pipelines
repository](https://github.com/matrix-org/pipelines).
We use the standard [Go testing package](https://gobyexample.com/testing) for this,
alongside some helper functions in our own [`test` package](https://pkg.go.dev/github.com/matrix-org/dendrite/test).
If a job fails, click the "details" button and you should be taken to the job's
logs.
## Continuous integration
![Click the details button on the failing build
step](https://raw.githubusercontent.com/matrix-org/dendrite/main/docs/images/details-button-location.jpg)
When a Pull Request is submitted, continuous integration jobs are run automatically
by GitHub actions to ensure that the code builds and works in a number of configurations,
such as different Go versions, using full HTTP APIs and both database engines.
CI will automatically run the unit tests (as above) as well as both of our integration
test suites ([Complement](https://github.com/matrix-org/complement) and
[SyTest](https://github.com/matrix-org/sytest)).
Scroll down to the failing step and you should see some log output. Scan the
logs until you find what it's complaining about, fix it, submit a new commit,
then rinse and repeat until CI passes.
You can see the progress of any CI jobs at the bottom of the Pull Request page, or by
looking at the [Actions](https://github.com/matrix-org/dendrite/actions) tab of the Dendrite
repository.
### Running CI Tests Locally
We generally won't accept a submission unless all of the CI jobs are passing. We
do understand though that sometimes the tests get things wrong — if that's the case,
please also raise a pull request to fix the relevant tests!
### Running CI tests locally
To save waiting for CI to finish after every commit, it is ideal to run the
checks locally before pushing, fixing errors first. This also saves other people
@ -70,7 +112,7 @@ passing tests.
If these two steps report no problems, the code should be able to pass the CI
tests.
## Picking Things To Do
## Picking things to do
If you're new then feel free to pick up an issue labelled [good first
issue](https://github.com/matrix-org/dendrite/labels/good%20first%20issue).
@ -86,17 +128,10 @@ We ask people who are familiar with Dendrite to leave the [good first
issue](https://github.com/matrix-org/dendrite/labels/good%20first%20issue)
issues so that there is always a way for new people to come and get involved.
## Getting Help
## Getting help
For questions related to developing on Dendrite we have a dedicated room on
Matrix [#dendrite-dev:matrix.org](https://matrix.to/#/#dendrite-dev:matrix.org)
where we're happy to help.
For more general questions please use
[#dendrite:matrix.org](https://matrix.to/#/#dendrite:matrix.org).
## Sign off
We ask that everyone who contributes to the project signs off their
contributions, in accordance with the
[DCO](https://github.com/matrix-org/matrix-spec/blob/main/CONTRIBUTING.rst#sign-off).
For more general questions please use [#dendrite:matrix.org](https://matrix.to/#/#dendrite:matrix.org).

64
docs/codestyle.md
View file

@ -1,64 +0,0 @@
---
title: Code Style
parent: Development
permalink: /development/codestyle
---
# Code Style
In addition to standard Go code style (`gofmt`, `goimports`), we use `golangci-lint`
to run a number of linters, the exact list can be found under linters in [.golangci.yml](.golangci.yml).
[Installation](https://github.com/golangci/golangci-lint#install-golangci-lint) and [Editor
Integration](https://golangci-lint.run/usage/integrations/#editor-integration) for
it can be found in the readme of golangci-lint.
For rare cases where a linter is giving a spurious warning, it can be disabled
for that line or statement using a [comment
directive](https://golangci-lint.run/usage/false-positives/#nolint), e.g. `var
bad_name int //nolint:golint,unused`. This should be used sparingly and only
when its clear that the lint warning is spurious.
The linters can be run using [build/scripts/find-lint.sh](/build/scripts/find-lint.sh)
(see file for docs) or as part of a build/test/lint cycle using
[build/scripts/build-test-lint.sh](/build/scripts/build-test-lint.sh).
##  Labels
In addition to `TODO` and `FIXME` we also use `NOTSPEC` to identify deviations
from the Matrix specification.
## Logging
We generally prefer to log with static log messages and include any dynamic
information in fields.
```golang
logger := util.GetLogger(ctx)
// Not recommended
logger.Infof("Finished processing keys for %s, number of keys %d", name, numKeys)
// Recommended
logger.WithFields(logrus.Fields{
"numberOfKeys": numKeys,
"entityName": name,
}).Info("Finished processing keys")
```
This is useful when logging to systems that natively understand log fields, as
it allows people to search and process the fields without having to parse the
log message.
## Visual Studio Code
If you use VSCode then the following is an example of a workspace setting that
sets up linting correctly:
```json
{
"go.lintTool":"golangci-lint",
"go.lintFlags": [
"--fast"
]
}
```

14
docs/installation/3_database.md
View file

@ -56,16 +56,16 @@ For either configuration, you will want to:
### Connection strings
Connection strings for PostgreSQL databases take the following form:
The format of connection strings for PostgreSQL databases is described in the [PostgreSQL libpq manual](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING). Note that Dendrite only
supports the "Connection URIs" format and **will not** work with the "Keyword/Value Connection
string" format.
Example supported connection strings take the format:
* `postgresql://user:pass@hostname/database?options=...`
* `postgres://user:pass@hostname/database?options=...`
For example, if you have a role called `dendrite` with the password `foobarbaz`, a database named
`dendrite` running on the same local machine, your connection string will be
`postgres://dendrite:foobarbaz@localhost/dendrite`.
If you need to disable SSL/TLS on the database connection, you can append `?sslmode=disable` to
the end of the connection string.
If you need to disable SSL/TLS on the database connection, you may need to append `?sslmode=disable` to the end of the connection string.
### Role creation

17
docs/installation/5_install_monolith.md
View file

@ -8,19 +8,14 @@ permalink: /installation/install/monolith
# Installing as a monolith
On UNIX systems, the `build.sh` script will build all variants of Dendrite.
You can install the Dendrite monolith binary into `$GOPATH/bin` by using `go install`:
```bash
./build.sh
```sh
go install ./cmd/dendrite-monolith-server
```
The `bin` directory will contain the built binaries.
Alternatively, you can specify a custom path for the binary to be written to using `go build`:
For monolith deployments, the relevant binary is the `dendrite-monolith-server`
binary.
Copy the `./bin/dendrite-monolith-server` into a relevant system path, for example:
```bash
cp ./bin/dendrite-monolith-server /usr/local/bin/
```sh
go build -o /usr/local/bin/ ./cmd/dendrite-monolith-server
```

19
docs/installation/6_install_polylith.md
View file

@ -8,20 +8,17 @@ permalink: /installation/install/polylith
# Installing as a polylith
On UNIX systems, the `build.sh` script will build all variants of Dendrite.
You can install the Dendrite polylith binary into `$GOPATH/bin` by using `go install`:
```sh
./build.sh
go install ./cmd/dendrite-polylith-multi
```
The `bin` directory will contain the built binaries.
Alternatively, you can specify a custom path for the binary to be written to using `go build`:
For polylith deployments, the relevant binary is the `dendrite-polylith-multi`
binary, which is a "multi-personality" binary which can run as any of the components
depending on the supplied command line parameters.
Copy the `./bin/dendrite-polylith-multi` into a relevant system path, for example:
```bash
cp ./bin/dendrite-polylith-multi /usr/local/bin/
```sh
go install -o /usr/local/bin/ ./cmd/dendrite-polylith-multi
```
The `dendrite-polylith-multi` binary is a "multi-personality" binary which can run as
any of the components depending on the supplied command line parameters.