New documentation: https://matrix-org.github.io/dendrite/
This commit is contained in:
Neil Alexander
parent
9599b3686e
commit
19a9166eb0
39 changed files with 1483 additions and 944 deletions
|
|
@ -1,55 +1,103 @@
|
|||
---
|
||||
title: Contributing
|
||||
parent: Development
|
||||
permalink: /development/contributing
|
||||
---
|
||||
|
||||
# Contributing to Dendrite
|
||||
|
||||
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
|
||||
```
|
||||
$ 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:
|
||||
|
||||
```
|
||||
$ go test ./...
|
||||
```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
|
||||
|
||||
|
||||
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
|
||||
time as only so many PRs can be tested at a given time.
|
||||
|
||||
To execute what Buildkite tests, first run `./build/scripts/build-test-lint.sh`; this
|
||||
To execute what CI tests, first run `./build/scripts/build-test-lint.sh`; this
|
||||
script will build the code, lint it, and run `go test ./...` with race condition
|
||||
checking enabled. If something needs to be changed, fix it and then run the
|
||||
script again until it no longer complains. Be warned that the linting can take a
|
||||
|
|
@ -64,8 +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).
|
||||
|
|
@ -81,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).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue