Skip to content

Commit 1fba419

Browse files
mtojekmtojek
authored
docs: add backend contributing guide (#18077)
1 parent 4597142 commit 1fba419

File tree

4 files changed

+265
-148
lines changed

4 files changed

+265
-148
lines changed

‎docs/CONTRIBUTING.md

Lines changed: 37 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44

55
<div class="tabs">
66

7-
We recommend that you use [Nix](https://nix.dev/) package manager to
8-
[maintain dependency versions](https://nixos.org/guides/how-nix-works).
7+
To get started with Coder, the easiest way to set up the required environment is to use the provided [Nix environment](https://github.com/coder/coder/tree/main/nix).
8+
Learn more [how Nix works](https://nixos.org/guides/how-nix-works).
99

1010
### Nix
1111

@@ -56,37 +56,9 @@ We recommend that you use [Nix](https://nix.dev/) package manager to
5656

5757
### Without Nix
5858

59-
Alternatively if you do not want to use Nix then you'll need to install the need
60-
the following tools by hand:
61-
62-
- Go 1.18+
63-
- on macOS, run `brew install go`
64-
- Node 14+
65-
- on macOS, run `brew install node`
66-
- GNU Make 4.0+
67-
- on macOS, run `brew install make`
68-
- [`shfmt`](https://github.com/mvdan/sh#shfmt)
69-
- on macOS, run `brew install shfmt`
70-
- [`nfpm`](https://nfpm.goreleaser.com/install)
71-
- on macOS, run `brew install goreleaser/tap/nfpm && brew install nfpm`
72-
- [`pg_dump`](https://stackoverflow.com/a/49689589)
73-
- on macOS, run `brew install libpq zstd`
74-
- on Linux, install [`zstd`](https://github.com/horta/zstd.install)
75-
- PostgreSQL 13 (optional if Docker is available)
76-
- *Note*: If you are using Docker, you can skip this step
77-
- on macOS, run `brew install postgresql@13` and `brew services start postgresql@13`
78-
- To enable schema generation with non-containerized PostgreSQL, set the following environment variable:
79-
- `export DB_DUMP_CONNECTION_URL="postgres://postgres@localhost:5432/postgres?password=postgres&sslmode=disable"`
80-
- `pkg-config`
81-
- on macOS, run `brew install pkg-config`
82-
- `pixman`
83-
- on macOS, run `brew install pixman`
84-
- `cairo`
85-
- on macOS, run `brew install cairo`
86-
- `pango`
87-
- on macOS, run `brew install pango`
88-
- `pandoc`
89-
- on macOS, run `brew install pandocomatic`
59+
If you're not using the Nix environment, you can launch a local [DevContainer](https://github.com/coder/coder/tree/main/.devcontainer) to get a fully configured development environment.
60+
61+
DevContainers are supported in tools like **VS Code** and **GitHub Codespaces**, and come preloaded with all required dependencies: Docker, Go, Node.js with `pnpm`, and `make`.
9062

9163
</div>
9264

@@ -101,19 +73,40 @@ Use the following `make` commands and scripts in development:
10173

10274
### Running Coder on development mode
10375

104-
- Run `./scripts/develop.sh`
105-
- Access `http://localhost:8080`
106-
- The default user is `admin@coder.com` and the default password is
107-
`SomeSecurePassword!`
76+
1. Run the development script to spin up the local environment:
77+
78+
```sh
79+
./scripts/develop.sh
80+
```
81+
82+
This will start two processes:
83+
84+
- http://localhost:3000 — the backend API server. Primarily used for backend development and also serves the *static* frontend build.
85+
- http://localhost:8080 — the Node.js frontend development server. Supports *hot reloading* and is useful if you're working on the frontend as well.
86+
87+
Additionally, it starts a local PostgreSQL instance, creates both an admin and a member user account, and installs a default Docker-based template.
88+
89+
1. Verify Your Session
10890

109-
### Running Coder using docker-compose
91+
Confirm that you're logged in by running:
11092

111-
This mode is useful for testing HA or validating more complex setups.
93+
```sh
94+
./scripts/coder-dev.sh list
95+
```
11296

113-
- Generate a new image from your HEAD: `make build/coder_$(./scripts/version.sh)_$(go env GOOS)_$(go env GOARCH).tag`
114-
- This will output the name of the new image, e.g.: `ghcr.io/coder/coder:v2.19.0-devel-22fa71d15-amd64`
115-
- Inject this image into docker-compose: `CODER_VERSION=v2.19.0-devel-22fa71d15-amd64 docker-compose up` (*note the prefix `ghcr.io/coder/coder:` was removed*)
116-
- To use Docker, determine your host's `docker` group ID with `getent group docker | cut -d: -f3`, then update the value of `group_add` and uncomment
97+
This should return an empty list of workspaces. If you encounter an error, review the output from the [develop.sh](https://github.com/coder/coder/blob/main/scripts/develop.sh) script for issues.
98+
99+
> `coder-dev.sh` is a helper script that behaves like the regular coder CLI, but uses the binary built from your local source and shares the same configuration directory set up by `develop.sh`. This ensures your local changes are reflected when testing.
100+
>
101+
> The default user is `admin@coder.com` and the default password is `SomeSecurePassword!`
102+
103+
1. Create Your First Workspace
104+
105+
A template named `docker` is created automatically. To spin up a workspace quickly, use:
106+
107+
```sh
108+
./scripts/coder-dev.sh create my-workspace -t docker
109+
```
117110

118111
### Deploying a PR
119112

@@ -148,110 +141,11 @@ Once the deployment is finished, a unique link and credentials will be posted in
148141
the [#pr-deployments](https://codercom.slack.com/archives/C05DNE982E8) Slack
149142
channel.
150143

151-
### Adding database migrations and fixtures
152-
153-
#### Database migrations
154-
155-
Database migrations are managed with
156-
[`migrate`](https://github.com/golang-migrate/migrate).
157-
158-
To add new migrations, use the following command:
159-
160-
```shell
161-
./coderd/database/migrations/create_migration.sh my name
162-
/home/coder/src/coder/coderd/database/migrations/000070_my_name.up.sql
163-
/home/coder/src/coder/coderd/database/migrations/000070_my_name.down.sql
164-
```
165-
166-
Then write queries into the generated `.up.sql` and `.down.sql` files and commit
167-
them into the repository. The down script should make a best-effort to retain as
168-
much data as possible.
169-
170-
Run `make gen` to generate models.
171-
172-
#### Database fixtures (for testing migrations)
173-
174-
There are two types of fixtures that are used to test that migrations don't
175-
break existing Coder deployments:
176-
177-
- Partial fixtures
178-
[`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
179-
- Full database dumps
180-
[`migrations/testdata/full_dumps`](../coderd/database/migrations/testdata/full_dumps)
181-
182-
Both types behave like database migrations (they also
183-
[`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors
184-
Coder migrations such that when migration number `000022` is applied, fixture
185-
`000022` is applied afterwards.
186-
187-
Partial fixtures are used to conveniently add data to newly created tables so
188-
that we can ensure that this data is migrated without issue.
189-
190-
Full database dumps are for testing the migration of fully-fledged Coder
191-
deployments. These are usually done for a specific version of Coder and are
192-
often fixed in time. A full database dump may be necessary when testing the
193-
migration of multiple features or complex configurations.
194-
195-
To add a new partial fixture, run the following command:
196-
197-
```shell
198-
./coderd/database/migrations/create_fixture.sh my fixture
199-
/home/coder/src/coder/coderd/database/migrations/testdata/fixtures/000070_my_fixture.up.sql
200-
```
201-
202-
Then add some queries to insert data and commit the file to the repo. See
203-
[`000024_example.up.sql`](../coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
204-
for an example.
205-
206-
To create a full dump, run a fully fledged Coder deployment and use it to
207-
generate data in the database. Then shut down the deployment and take a snapshot
208-
of the database.
209-
210-
```shell
211-
mkdir -p coderd/database/migrations/testdata/full_dumps/v0.12.2 && cd $_
212-
pg_dump "postgres://coder@localhost:..." -a --inserts >000069_dump_v0.12.2.up.sql
213-
```
214-
215-
Make sure sensitive data in the dump is desensitized, for instance names,
216-
emails, OAuth tokens and other secrets. Then commit the dump to the project.
217-
218-
To find out what the latest migration for a version of Coder is, use the
219-
following command:
220-
221-
```shell
222-
git ls-files v0.12.2 -- coderd/database/migrations/*.up.sql
223-
```
224-
225-
This helps in naming the dump (e.g. `000069` above).
226-
227144
## Styling
228145

229-
### Documentation
230-
231146
Visit our [documentation style guide](./contributing/documentation.md).
232147

233-
### Backend
234-
235-
#### Use Go style
236-
237-
Contributions must adhere to the guidelines outlined in
238-
[Effective Go](https://go.dev/doc/effective_go). We prefer linting rules over
239-
documenting styles (run ours with `make lint`); humans are error-prone!
240-
241-
Read
242-
[Go's Code Review Comments Wiki](https://github.com/golang/go/wiki/CodeReviewComments)
243-
for information on common comments made during reviews of Go code.
244-
245-
#### Avoid unused packages
246-
247-
Coder writes packages that are used during implementation. It isn't easy to
248-
validate whether an abstraction is valid until it's checked against an
249-
implementation. This results in a larger changeset, but it provides reviewers
250-
with a holistic perspective regarding the contribution.
251-
252-
### Frontend
253-
254-
Our frontend guide can be found [here](./contributing/frontend.md).
148+
Frontend styling guide can be found [here](./contributing/frontend.md#styling).
255149

256150
## Reviews
257151

0 commit comments

Comments
 (0)