Requirements

Development workflow

Use the followingmake commands and scripts in development:

• ./scripts/develop.sh runs the frontend and backend development server
• make build compiles binaries and release packages
• make install installs binaries to$GOPATH/bin
• make test

Running Coder on development mode

1. Run the development script to spin up the local environment:

   ./scripts/develop.sh

   This will start two processes:

   • http://localhost:3000 — the backend API server. Primarily used for backend development and also serves thestatic frontend build.
   • http://localhost:8080 — the Node.js frontend development server. Supportshot 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.

2. Verify Your Session

   Confirm that you're logged in by running:

   ./scripts/coder-dev.sh list

   This should return an empty list of workspaces. If you encounter an error, review the output from thedevelop.sh script for issues.

   Note

   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 bydevelop.sh. This ensures your local changes are reflected when testing.

   The default user is[email protected] and the default password isSomeSecurePassword!

3. Create Your First Workspace

   A template nameddocker is created automatically. To spin up a workspace quickly, use:

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

Deploying a PR

You need to be a member or collaborator of thecoder GitHub organization to be able to deploy a PR.

You can test your changes by creating a PR deployment. There are two ways to dothis:

• Run./scripts/deploy-pr.sh

• Manually trigger thepr-deploy.yamlGitHub Action workflow:

  

Available options

• -d or--deploy, force deploys the PR by deleting the existing deployment.
• -b or--build, force builds the Docker image. (generally not needed as weare intelligently checking if the image needs to be built)
• -e EXPERIMENT1,EXPERIMENT2 or--experiments EXPERIMENT1,EXPERIMENT2, willenable the specified experiments. (defaults to*)
• -n or--dry-run will display the context without deployment. e.g., branchname and PR number, etc.
• -y or--yes, will skip the CLI confirmation prompt.

Once the deployment is finished, a unique link and credentials will be posted inthe#pr-deployments Slackchannel.

Styling

• Documentation style guide

• Frontend styling guide

Pull Requests

We welcome pull requests (PRs) from community members including (but not limited to) open source users, enthusiasts, and enterprise customers.

We will ask that you sign a Contributor License Agreement before we accept any contributions into our repo.

Please keep PRs small and self-contained. This allows code reviewers (see below) to focus and fully understand the PR. A good rule of thumb is less than 1000 lines changed. (One exception is a mechanistic refactor, like renaming, that is conceptually trivial but might have a large line count.)

If your intended feature or refactor will be larger than this:

1. Open an issue explaining what you intend to build, how it will work, and that you are volunteering to do the development. Include@coder/community-triage in the body.
2. Give the maintainers a chance to respond. Changes to the visual, interaction, or software design are easier to adjust before you start laying down code.
3. Break your work up into a series of smaller PRs.

Stacking tools likeGraphite are useful for keeping a series of PRs that build on each other up to date as they are reviewed and merged.

Each PR:

• Must individually build and pass all tests, including formatting and linting.
• Must not introduce regressions or backward-compatibility issues, even if a subsequent PR in your series would resolve the issue.
• Should be a conceptually coherent change set.

In practice, many of these smaller PRs will be invisible to end users, and that is ok. For example, you might introducea new Go package that implements the core business logic of a feature in one PR, but only later actually "wire it up"to a new API route in a later PR. Or, you might implement a new React component in one PR, and only in a later PR place it on a page.

Reviews

The following information has been borrowed fromGo's review philosophy.

Coder values thorough reviews. For each review comment that you receive, please"close" it by implementing the suggestion or providing an explanation on why thesuggestion isn't the best option. Be sure to do this for each comment; you canclickDone to indicate that you've implemented the suggestion, or you canadd a comment explaining why you aren't implementing the suggestion (or what youchose to implement instead).

It is perfectly normal for changes to go through several rounds of reviews, withone or more reviewers making new comments every time, then waiting for anupdated change before reviewing again. All contributors, including those frommaintainers, are subject to the same review cycle; this process is not meant tobe applied selectively or to discourage anyone from contributing.

Releases

Coder releases are initiated via./scripts/release.shand automated via GitHub Actions. Specifically, therelease.yamlworkflow. They are created based on the currentmain branch.

The release notes for a release are automatically generated from commit titlesand metadata from PRs that are merged intomain.

Creating a release

The creation of a release is initiated via./scripts/release.sh.This script will show a preview of the release that will be created, and if youchoose to continue, create and push the tag which will trigger the creation ofthe release via GitHub Actions.

See./scripts/release.sh --help for more information.

Creating a release (via workflow dispatch)

Typically the workflow dispatch is only used to test (dry-run) a release,meaning no actual release will take place. The workflow can be dispatchedmanually fromActions: Release.Simply press "Run workflow" and choose dry-run.

If a release has failed after the tag has been created and pushed, it can beretried by again, pressing "Run workflow", changing "Use workflow from" from"Branch: main" to "Tag: vX.X.X" and not selecting dry-run.

Commit messages

Commit messages should follow theConventional Commits 1.0.0specification.

Allowed commit types (feat,fix, etc.) are listed inconventional-commit-types.Note that these types are also used to automatically sort and organize therelease notes.

A good commit message title uses the imperative, present tense and is ~50characters long (no more than 72).

Examples:

• Good:feat(api): add feature X
• Bad:feat(api): added feature X (past tense)

A good rule of thumb for writing good commit messages is to recite:If applied, this commit will ....

Note: We lint PR titles to ensure they follow the Conventional Commitsspecification, however, it's still possible to merge PRs on GitHub with a badlyformatted title. Take care when merging single-commit PRs as GitHub may preferto use the original commit title instead of the PR title.

Breaking changes

Breaking changes can be triggered in two ways:

• Add! to the commit message title, e.g.feat(api)!: remove deprecated endpoint /test
• Add therelease/breakinglabel to a PR that has, or will be, merged intomain.

Generative AI

Using AI to help with contributions is acceptable, but only if theAI Contribution Guidelinesare followed. If most of your PR was generated by AI, please read and comply with these rules before submitting.

Security

Thesecuritylabel can be added to PRs that have, or will be, merged intomain. Doing sowill make sure the change stands out in the release notes.

Experimental

Therelease/experimentallabel can be used to move the note to the bottom of the release notes under aseparate title.

Troubleshooting

Nix on macOS:error: creating directory

On macOS, adirenv bug can causenix-shell to fail to build or runcoder. If you encountererror: creating directory when you attempt to run, build, or test, add amkdir line to your.envrc: