diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index ce6d4980d..51426b2a0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -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 +``` + +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). diff --git a/docs/codestyle.md b/docs/codestyle.md deleted file mode 100644 index 7e3f50a0f..000000000 --- a/docs/codestyle.md +++ /dev/null @@ -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" - ] -} -``` diff --git a/docs/installation/3_database.md b/docs/installation/3_database.md index 46b600c98..f64fe9150 100644 --- a/docs/installation/3_database.md +++ b/docs/installation/3_database.md @@ -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 diff --git a/docs/installation/5_install_monolith.md b/docs/installation/5_install_monolith.md index e7d90c52b..7de066cf7 100644 --- a/docs/installation/5_install_monolith.md +++ b/docs/installation/5_install_monolith.md @@ -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 ``` diff --git a/docs/installation/6_install_polylith.md b/docs/installation/6_install_polylith.md index dd0fc731f..745cdd6d4 100644 --- a/docs/installation/6_install_polylith.md +++ b/docs/installation/6_install_polylith.md @@ -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.