mirror of
https://github.com/1f349/dendrite.git
synced 2024-11-09 22:42:58 +00:00
Add Code Style and some dev docs (#286)
This commit is contained in:
parent
5229dbf310
commit
1e6fc74d4f
63
CODE_STYLE.md
Normal file
63
CODE_STYLE.md
Normal file
@ -0,0 +1,63 @@
|
||||
# Code Style
|
||||
|
||||
We follow the standard Go style using gofmt, but with a few extra
|
||||
considerations.
|
||||
|
||||
## Linters
|
||||
|
||||
We use `gometalinter` to run a number of linters, the exact list can be found
|
||||
in [linter.json](linter.json). Some of these are slow and expensive to run, but
|
||||
a subset can be found in [linter-fast.json](linter-fast.json) that run quickly
|
||||
enough to be run as part of an IDE.
|
||||
|
||||
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://github.com/alecthomas/gometalinter#comment-directives), e.g.
|
||||
`// nolint: gocyclo`. This should be used sparingly and only when its clear
|
||||
that the lint warning is spurious.
|
||||
|
||||
|
||||
## HTTP Error Handling
|
||||
|
||||
Unfortunately, converting errors into HTTP responses with the correct status
|
||||
code and message can be done in a number of ways in golang:
|
||||
|
||||
1. Having functions return `JSONResponse` directly, which can then either set
|
||||
it to an error response or a `200 OK`.
|
||||
2. Have the HTTP handler try and cast error values to types that are handled
|
||||
differently.
|
||||
3. Have the HTTP handler call functions whose errors can only be interpreted
|
||||
one way, for example if a `validate(...)` call returns an error then handler
|
||||
knows to respond with a `400 Bad Request`.
|
||||
|
||||
We attempt to always use option #3, as it more naturally fits with the way that
|
||||
golang generally does error handling. In particular, option #1 effectively
|
||||
requires reinventing a new error handling scheme just for HTTP handlers.
|
||||
|
||||
|
||||
## Line length
|
||||
|
||||
We strive for a line length of roughly 80 characters, though less than 100 is
|
||||
acceptable if necessary. Longer lines are fine if there is nothing of interest
|
||||
after the first 80-100 characters (e.g. long string literals).
|
||||
|
||||
|
||||
## TODOs and FIXMEs
|
||||
|
||||
The majority of TODOs and FIXMEs should have an associated tracking issue on
|
||||
github. These can be added just before merging of the PR to master, and the
|
||||
issue number should be added to the comment, e.g. `// TODO(#324): ...`
|
||||
|
||||
|
||||
## Visual Studio Code
|
||||
|
||||
If you use VSCode then the following is an example of a workspace setting that
|
||||
sets up linting correctly:
|
||||
|
||||
```json
|
||||
{
|
||||
"go.gopath": "${workspaceRoot}:${workspaceRoot}/vendor",
|
||||
"go.lintOnSave": "workspace",
|
||||
"go.lintTool": "gometalinter",
|
||||
"go.lintFlags": ["--config=linter-fast.json", "--concurrency=5"]
|
||||
}
|
||||
```
|
@ -3,6 +3,19 @@
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
We use `gb` for managing our dependencies, so `gb build` and `gb test` is how
|
||||
to build dendrite and run the unit tests respectively.
|
||||
|
||||
|
||||
## Picking Things To Do
|
||||
|
||||
If you're new then feel free to pick up an issue labelled [easy](https://github.com/matrix-org/dendrite/labels/easy).
|
||||
|
@ -5,7 +5,7 @@ Dendrite can be run in one of two configurations:
|
||||
* A cluster of individual components, dealing with different aspects of the
|
||||
Matrix protocol (see [WIRING.md](./WIRING.md)). Components communicate with
|
||||
one another via [Apache Kafka](https://kafka.apache.org).
|
||||
|
||||
|
||||
* A monolith server, in which all components run in the same process. In this
|
||||
configuration, Kafka can be replaced with an in-process implementation
|
||||
called [naffka](https://github.com/matrix-org/naffka).
|
||||
@ -17,7 +17,7 @@ Dendrite can be run in one of two configurations:
|
||||
- For Kafka (optional if using the monolith server):
|
||||
- Unix-based system (https://kafka.apache.org/documentation/#os)
|
||||
- JDK 1.8+ / OpenJDK 1.8+
|
||||
- Apache Kafka 0.10.2+ (see https://github.com/matrix-org/dendrite/blob/master/travis-install-kafka.sh for up-to-date version numbers)
|
||||
- Apache Kafka 0.10.2+ (see [travis-install-kafka.sh](travis-install-kafka.sh) for up-to-date version numbers)
|
||||
|
||||
|
||||
## Setting up a development environment
|
||||
@ -34,7 +34,7 @@ go get github.com/constabulary/gb/...
|
||||
gb build
|
||||
```
|
||||
|
||||
If using Kafka, install and start it:
|
||||
If using Kafka, install and start it (c.f. [travis-install-kafka.sh](travis-install-kafka.sh)):
|
||||
```bash
|
||||
MIRROR=http://apache.mirror.anlx.net/kafka/0.10.2.0/kafka_2.11-0.10.2.0.tgz
|
||||
|
||||
@ -108,7 +108,7 @@ The following contains scripts which will run all the required processes in orde
|
||||
|
||||
```
|
||||
|
||||
/media +---------------------------+
|
||||
/media +---------------------------+
|
||||
+----------->+------------->| dendrite-media-api-server |
|
||||
^ ^ +---------------------------+
|
||||
| | :7774
|
||||
|
Loading…
Reference in New Issue
Block a user