May 30, 2025 · May 27, 2025 · May 27, 2025 · May 27, 2025 · May 27, 2025 · May 28, 2025
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md

 <div class="tabs">

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

 ### Nix


 ### Without Nix

 Alternatively if you do not want to use Nix then you'll need to install the need
 the following tools by hand:

 - Go 1.18+
  - on macOS, run `brew install go`
 - Node 14+
  - on macOS, run `brew install node`
 - GNU Make 4.0+
  - on macOS, run `brew install make`
 - [`shfmt`](https://github.com/mvdan/sh#shfmt)
  - on macOS, run `brew install shfmt`
 - [`nfpm`](https://nfpm.goreleaser.com/install)
  - on macOS, run `brew install goreleaser/tap/nfpm && brew install nfpm`
 - [`pg_dump`](https://stackoverflow.com/a/49689589)
  - on macOS, run `brew install libpq zstd`
  - on Linux, install [`zstd`](https://github.com/horta/zstd.install)
 - PostgreSQL 13 (optional if Docker is available)
  - *Note*: If you are using Docker, you can skip this step
  - on macOS, run `brew install postgresql@13` and `brew services start postgresql@13`
  - To enable schema generation with non-containerized PostgreSQL, set the following environment variable:
    - `export DB_DUMP_CONNECTION_URL="postgres://postgres@localhost:5432/postgres?password=postgres&sslmode=disable"`
 - `pkg-config`
  - on macOS, run `brew install pkg-config`
 - `pixman`
  - on macOS, run `brew install pixman`
 - `cairo`
  - on macOS, run `brew install cairo`
 - `pango`
  - on macOS, run `brew install pango`
 - `pandoc`
  - on macOS, run `brew install pandocomatic`
 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.

 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`.

 </div>


 ### Running Coder on development mode

 - Run `./scripts/develop.sh`
 - Access `http://localhost:8080`
 - The default user is `admin@coder.com` and the default password is
  `SomeSecurePassword!`
 1. Run the development script to spin up the local environment:

   ```sh
   ./scripts/develop.sh
   ```

   This will start two processes:

   - http://localhost:3000 — the backend API server. Primarily used for backend development and also serves the *static* frontend build.
   - http://localhost:8080 — the Node.js frontend development server. Supports *hot reloading* and is useful if you're working on the frontend as well.

   Additionally, it starts a local PostgreSQL instance, creates both an admin and a member user account, and installs a default Docker-based template.

 1. Verify Your Session

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

 This mode is useful for testing HA or validating more complex setups.
   ```sh
   ./scripts/coder-dev.sh list
      ```

 - Generate a new image from your HEAD: `make build/coder_$(./scripts/version.sh)_$(go env GOOS)_$(go env GOARCH).tag`
  - This will output the name of the new image, e.g.: `ghcr.io/coder/coder:v2.19.0-devel-22fa71d15-amd64`
 - 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*)
 - 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
   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.

   > `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.
   >
   > The default user is `admin@coder.com` and the default password is `SomeSecurePassword!`

 1. Create Your First Workspace

   A template named `docker` is created automatically. To spin up a workspace quickly, use:

   ```sh
   ./scripts/coder-dev.sh create my-workspace -t docker
   ```

 ### Deploying a PR

 the [#pr-deployments](https://codercom.slack.com/archives/C05DNE982E8) Slack
 channel.

 ### Adding database migrations and fixtures

 #### Database migrations

 Database migrations are managed with
 [`migrate`](https://github.com/golang-migrate/migrate).

 To add new migrations, use the following command:

 ```shell
 ./coderd/database/migrations/create_migration.sh my name
 /home/coder/src/coder/coderd/database/migrations/000070_my_name.up.sql
 /home/coder/src/coder/coderd/database/migrations/000070_my_name.down.sql
 ```

 Then write queries into the generated `.up.sql` and `.down.sql` files and commit
 them into the repository. The down script should make a best-effort to retain as
 much data as possible.

 Run `make gen` to generate models.

 #### Database fixtures (for testing migrations)

 There are two types of fixtures that are used to test that migrations don't
 break existing Coder deployments:

 - Partial fixtures
  [`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
 - Full database dumps
  [`migrations/testdata/full_dumps`](../coderd/database/migrations/testdata/full_dumps)

 Both types behave like database migrations (they also
 [`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors
 Coder migrations such that when migration number `000022` is applied, fixture
 `000022` is applied afterwards.

 Partial fixtures are used to conveniently add data to newly created tables so
 that we can ensure that this data is migrated without issue.

 Full database dumps are for testing the migration of fully-fledged Coder
 deployments. These are usually done for a specific version of Coder and are
 often fixed in time. A full database dump may be necessary when testing the
 migration of multiple features or complex configurations.

 To add a new partial fixture, run the following command:

 ```shell
 ./coderd/database/migrations/create_fixture.sh my fixture
 /home/coder/src/coder/coderd/database/migrations/testdata/fixtures/000070_my_fixture.up.sql
 ```

 Then add some queries to insert data and commit the file to the repo. See
 [`000024_example.up.sql`](../coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
 for an example.

 To create a full dump, run a fully fledged Coder deployment and use it to
 generate data in the database. Then shut down the deployment and take a snapshot
 of the database.

 ```shell
 mkdir -p coderd/database/migrations/testdata/full_dumps/v0.12.2 && cd $_
 pg_dump "postgres://coder@localhost:..." -a --inserts >000069_dump_v0.12.2.up.sql
 ```

 Make sure sensitive data in the dump is desensitized, for instance names,
 emails, OAuth tokens and other secrets. Then commit the dump to the project.

 To find out what the latest migration for a version of Coder is, use the
 following command:

 ```shell
 git ls-files v0.12.2 -- coderd/database/migrations/*.up.sql
 ```

 This helps in naming the dump (e.g. `000069` above).

 ## Styling

 ### Documentation

 Visit our [documentation style guide](./contributing/documentation.md).

 ### Backend

 #### Use Go style

 Contributions must adhere to the guidelines outlined in
 [Effective Go](https://go.dev/doc/effective_go). We prefer linting rules over
 documenting styles (run ours with `make lint`); humans are error-prone!

 Read
 [Go's Code Review Comments Wiki](https://github.com/golang/go/wiki/CodeReviewComments)
 for information on common comments made during reviews of Go code.

 #### Avoid unused packages

 Coder writes packages that are used during implementation. It isn't easy to
 validate whether an abstraction is valid until it's checked against an
 implementation. This results in a larger changeset, but it provides reviewers
 with a holistic perspective regarding the contribution.

 ### Frontend

 Our frontend guide can be found [here](./contributing/frontend.md).
 Frontend styling guide can be found [here](./contributing/frontend.md#styling).

 ## Reviews
Original file line number	Diff line number	Diff line change
Expand Up		@@ -4,8 +4,8 @@

		<div class="tabs">

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

		### Nix

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

		### Without Nix

		Alternatively if you do not want to use Nix then you'll need to install the need
		the following tools by hand:

		- Go 1.18+
		- on macOS, run `brew install go`
		- Node 14+
		- on macOS, run `brew install node`
		- GNU Make 4.0+
		- on macOS, run `brew install make`
		- [`shfmt`](https://github.com/mvdan/sh#shfmt)
		- on macOS, run `brew install shfmt`
		- [`nfpm`](https://nfpm.goreleaser.com/install)
		- on macOS, run `brew install goreleaser/tap/nfpm && brew install nfpm`
		- [`pg_dump`](https://stackoverflow.com/a/49689589)
		- on macOS, run `brew install libpq zstd`
		- on Linux, install [`zstd`](https://github.com/horta/zstd.install)
		- PostgreSQL 13 (optional if Docker is available)
		- Note: If you are using Docker, you can skip this step
		- on macOS, run `brew install postgresql@13` and `brew services start postgresql@13`
		- To enable schema generation with non-containerized PostgreSQL, set the following environment variable:
		- `export DB_DUMP_CONNECTION_URL="postgres://postgres@localhost:5432/postgres?password=postgres&sslmode=disable"`
		- `pkg-config`
		- on macOS, run `brew install pkg-config`
		- `pixman`
		- on macOS, run `brew install pixman`
		- `cairo`
		- on macOS, run `brew install cairo`
		- `pango`
		- on macOS, run `brew install pango`
		- `pandoc`
		- on macOS, run `brew install pandocomatic`
		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.

		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`.

		</div>

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

		### Running Coder on development mode

		- Run `./scripts/develop.sh`
		- Access `http://localhost:8080`
		- The default user is `admin@coder.com` and the default password is
		`SomeSecurePassword!`
		1. Run the development script to spin up the local environment:

		```sh
		./scripts/develop.sh
		```

		This will start two processes:

		- http://localhost:3000 — the backend API server. Primarily used for backend development and also serves the static frontend build.
		- http://localhost:8080 — the Node.js frontend development server. Supports hot reloading and is useful if you're working on the frontend as well.

		Additionally, it starts a local PostgreSQL instance, creates both an admin and a member user account, and installs a default Docker-based template.

		1. Verify Your Session

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

		This mode is useful for testing HA or validating more complex setups.
		```sh
		./scripts/coder-dev.sh list
		```

		- Generate a new image from your HEAD: `make build/coder_$(./scripts/version.sh)_$(go env GOOS)_$(go env GOARCH).tag`
		- This will output the name of the new image, e.g.: `ghcr.io/coder/coder:v2.19.0-devel-22fa71d15-amd64`
		- 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)
		- 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
		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.

		> `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.
		>
		> The default user is `admin@coder.com` and the default password is `SomeSecurePassword!`

		1. Create Your First Workspace

		A template named `docker` is created automatically. To spin up a workspace quickly, use:

		```sh
		./scripts/coder-dev.sh create my-workspace -t docker
		```

		### Deploying a PR

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

		### Adding database migrations and fixtures

		#### Database migrations

		Database migrations are managed with
		[`migrate`](https://github.com/golang-migrate/migrate).

		To add new migrations, use the following command:

		```shell
		./coderd/database/migrations/create_migration.sh my name
		/home/coder/src/coder/coderd/database/migrations/000070_my_name.up.sql
		/home/coder/src/coder/coderd/database/migrations/000070_my_name.down.sql
		```

		Then write queries into the generated `.up.sql` and `.down.sql` files and commit
		them into the repository. The down script should make a best-effort to retain as
		much data as possible.

		Run `make gen` to generate models.

		#### Database fixtures (for testing migrations)

		There are two types of fixtures that are used to test that migrations don't
		break existing Coder deployments:

		- Partial fixtures
		[`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
		- Full database dumps
		[`migrations/testdata/full_dumps`](../coderd/database/migrations/testdata/full_dumps)

		Both types behave like database migrations (they also
		[`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors
		Coder migrations such that when migration number `000022` is applied, fixture
		`000022` is applied afterwards.

		Partial fixtures are used to conveniently add data to newly created tables so
		that we can ensure that this data is migrated without issue.

		Full database dumps are for testing the migration of fully-fledged Coder
		deployments. These are usually done for a specific version of Coder and are
		often fixed in time. A full database dump may be necessary when testing the
		migration of multiple features or complex configurations.

		To add a new partial fixture, run the following command:

		```shell
		./coderd/database/migrations/create_fixture.sh my fixture
		/home/coder/src/coder/coderd/database/migrations/testdata/fixtures/000070_my_fixture.up.sql
		```

		Then add some queries to insert data and commit the file to the repo. See
		[`000024_example.up.sql`](../coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
		for an example.

		To create a full dump, run a fully fledged Coder deployment and use it to
		generate data in the database. Then shut down the deployment and take a snapshot
		of the database.

		```shell
		mkdir -p coderd/database/migrations/testdata/full_dumps/v0.12.2 && cd $_
		pg_dump "postgres://coder@localhost:..." -a --inserts >000069_dump_v0.12.2.up.sql
		```

		Make sure sensitive data in the dump is desensitized, for instance names,
		emails, OAuth tokens and other secrets. Then commit the dump to the project.

		To find out what the latest migration for a version of Coder is, use the
		following command:

		```shell
		git ls-files v0.12.2 -- coderd/database/migrations/*.up.sql
		```

		This helps in naming the dump (e.g. `000069` above).

		## Styling

		### Documentation

		Visit our [documentation style guide](./contributing/documentation.md).

		### Backend

		#### Use Go style

		Contributions must adhere to the guidelines outlined in
		[Effective Go](https://go.dev/doc/effective_go). We prefer linting rules over
		documenting styles (run ours with `make lint`); humans are error-prone!

		Read
		[Go's Code Review Comments Wiki](https://github.com/golang/go/wiki/CodeReviewComments)
		for information on common comments made during reviews of Go code.

		#### Avoid unused packages

		Coder writes packages that are used during implementation. It isn't easy to
		validate whether an abstraction is valid until it's checked against an
		implementation. This results in a larger changeset, but it provides reviewers
		with a holistic perspective regarding the contribution.

		### Frontend

		Our frontend guide can be found [here](./contributing/frontend.md).
		Frontend styling guide can be found [here](./contributing/frontend.md#styling).

		## Reviews

Expand Down