mirror of
https://github.com/coder/coder.git
synced 2026-10-16 14:48:56 +08:00
docs: move contributor guides out of the published docs into the repo (#29751)
## Merge order Merge first; then republish the docs; then coder/coder.com#1100 (the redirects). ## Summary The nine pages under `docs/about/contributing/` are for people working in this repository, not for Coder users or administrators, so they leave the published documentation. The repository becomes their canonical home. Until now the root `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` were two-line stubs that only linked to the docs site, so contributors on GitHub were bounced out to read them. A companion PR in `coder/coder.com` adds redirects from every retired `/docs/about/contributing/*` URL to the new GitHub location. It must merge only after this PR has merged and the docs have republished. ## Changes | Old path | New path | | -- | -- | | `docs/about/contributing/CONTRIBUTING.md` | `CONTRIBUTING.md` (replaces the stub) | | `docs/about/contributing/CODE_OF_CONDUCT.md` | `CODE_OF_CONDUCT.md` (replaces the stub) | | `docs/about/contributing/SECURITY.md` | deleted; the root `SECURITY.md` already holds the policy | | `docs/about/contributing/AI_CONTRIBUTING.md` | `contributing/AI_CONTRIBUTING.md` | | `docs/about/contributing/backend.md` | `contributing/backend.md` | | `docs/about/contributing/frontend.md` | `contributing/frontend.md` | | `docs/about/contributing/modules.md` | `contributing/modules.md` | | `docs/about/contributing/templates.md` | `contributing/templates.md` | | `docs/about/contributing/documentation.md` | `contributing/documentation.md` (see note below) | For every moved file: the docs front matter is stripped and its `title` becomes the H1, relative links are rewritten for the new depth (`../../../foo` becomes `./foo` at the root and `../foo` under `contributing/`; the two links into `docs/admin/` become `../docs/admin/...`), and the docs-only `<div class="tabs">` wrapper in `CONTRIBUTING.md` is removed. `CONTRIBUTING.md` gains a short intro that links the code of conduct, the security policy and the area guides, since GitHub only auto-surfaces the root files. `docs/manifest.json` loses the About → Contributing group and `docs/images/icons/contributing.svg`, which only that group used. Inbound references updated: - `README.md`: contribution guide link now points at `CONTRIBUTING.md` on GitHub. - `docs/tutorials/example-guide.md` and `docs/install/releases/feature-stages.md`: link to `contributing/documentation.md` on GitHub, since a docs page cannot link to a repo-only file. - `docs/.style/style-guide/README.md`: the "Relationship to" section names the new location. - `scripts/docshtmlcheck/main.go`: both the package comment and the user-facing error string name `contributing/documentation.md`. - `scripts/docshtmlcheck/README.md`: relative link to the new location. - `coderd/database/migrations/migrate_test.go`: `t.Log` link now points at `contributing/backend.md#database-fixtures-for-testing-migrations`. - `.github/pull_request_template.md`: AI contribution guidelines link. - `.github/workflows/contrib.yaml`: commit-message guidelines link in the PR title check. - `.github/workflows/test-docs-preview-mapper.sh`: the mapper test case that used `docs/about/contributing/CONTRIBUTING.md` now uses `docs/admin/security/audit-logs.md`. - `.claude/docs/{ARCHITECTURE,PR_STYLE_GUIDE,WORKFLOWS,DOCS_STYLE_GUIDE}.md`: links to `CONTRIBUTING.md`. `git grep about/contributing` is empty after this change. `CODEOWNERS` had no entry for the old paths. Note on `documentation.md`: it is docs-authoring guidance and is parked in `contributing/` for now. Folding it into `docs/.style/` is tracked separately and is deliberately not attempted here. ## Testing - `go run ./scripts/docshtmlcheck` over `docs/`, and again over `contributing/`, `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`: clean. - `go vet ./scripts/docshtmlcheck/...` and `go test ./scripts/docshtmlcheck/...`: 47 tests pass. - `go vet ./coderd/database/migrations/...`: clean. `go test` for that package fails to link on this machine (`tailscale.com/tstime/mono: invalid reference to runtime.nanotime1`) identically on unmodified `main`, so it is a local toolchain issue and not exercised here; the change is a string in a `t.Log`. - `pnpm check-docs` (markdownlint-cli2 and markdown-table-formatter over `docs/`, `.claude/docs/`, root `*.md`): 495 files, 0 errors. The same two tools over `contributing/*.md`: 0 errors. - Every relative link in the eight moved files resolves to an existing path (scripted check). - `bash .github/workflows/test-docs-preview-mapper.sh`: the changed `assert_maps_to` case passes; the six `resolve_ref`/`pages_for_image` failures it reports are identical on unmodified `main` on macOS. Linear: [DOCS-975](https://linear.app/codercom/issue/DOCS-975) --- 🤖 Built with AI assistance.
This commit is contained in:
Nick Vigilante
@@ -113,7 +113,7 @@ Coder emphasizes clear error handling, with specific patterns required:
|
||||
|
||||
All tests should run in parallel using `t.Parallel()` to ensure efficient testing and expose potential race conditions. The codebase is rigorously linted with golangci-lint to maintain consistent code quality.
|
||||
|
||||
Git contributions follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). See [CONTRIBUTING.md](docs/about/contributing/CONTRIBUTING.md#commit-messages) for full rules. PR titles are linted in CI.
|
||||
Git contributions follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). See [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages) for full rules. PR titles are linted in CI.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ This guide documents structure, research, and content patterns for documentation
|
||||
> Refer to [What the tooling checks, and what it doesn't](../../docs/.style/style-guide/README.md#what-the-tooling-checks-and-what-it-doesnt).
|
||||
> This file remains authoritative for structure, research, and content patterns.
|
||||
|
||||
See [CONTRIBUTING.md](../../docs/about/contributing/CONTRIBUTING.md) for general contribution guidelines.
|
||||
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for general contribution guidelines.
|
||||
|
||||
## Research Before Writing
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ This guide documents the PR description style used in the Coder repository, base
|
||||
|
||||
## PR Title Format
|
||||
|
||||
Format: `type(scope): description`. See [CONTRIBUTING.md](docs/about/contributing/CONTRIBUTING.md#commit-messages) for full rules. PR titles are linted in CI.
|
||||
Format: `type(scope): description`. See [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages) for full rules. PR titles are linted in CI.
|
||||
|
||||
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
|
||||
- Scopes must be a real path (directory or file stem) containing all changed files
|
||||
|
||||
@@ -192,7 +192,7 @@ Then make your changes and push normally. Don't use `git push --force` unless th
|
||||
|
||||
## Commit Style
|
||||
|
||||
Format: `type(scope): message`. See [CONTRIBUTING.md](docs/about/contributing/CONTRIBUTING.md#commit-messages) for full rules. PR titles are linted in CI.
|
||||
Format: `type(scope): message`. See [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages) for full rules. PR titles are linted in CI.
|
||||
|
||||
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
|
||||
- Scopes must be a real path (directory or file stem) containing all changed files
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
|
||||
If you have used AI to produce some or all of this PR, please ensure you have read our [AI Contribution guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) before submitting.
|
||||
If you have used AI to produce some or all of this PR, please ensure you have read our [AI Contribution guidelines](https://github.com/coder/coder/blob/main/contributing/AI_CONTRIBUTING.md) before submitting.
|
||||
|
||||
-->
|
||||
|
||||
@@ -134,7 +134,7 @@ jobs:
|
||||
"perf", "test", "build", "ci", "chore", "revert",
|
||||
];
|
||||
const expectedFormat = `"type(scope): description" or "type: description"`;
|
||||
const guidelinesLink = `See: https://github.com/coder/coder/blob/main/docs/about/contributing/CONTRIBUTING.md#commit-messages`;
|
||||
const guidelinesLink = `See: https://github.com/coder/coder/blob/main/CONTRIBUTING.md#commit-messages`;
|
||||
const scopeHint = (type) =>
|
||||
`Use a broader scope or no scope (e.g., "${type}: ...") for cross-cutting changes.\n` +
|
||||
guidelinesLink;
|
||||
|
||||
@@ -77,7 +77,7 @@ assert_maps_to "docs/CHANGELOG.md" "CHANGELOG"
|
||||
|
||||
# Additional coverage for edge cases and deeper nesting.
|
||||
assert_maps_to "docs/index.md" ""
|
||||
assert_maps_to "docs/about/contributing/CONTRIBUTING.md" "about/contributing/CONTRIBUTING"
|
||||
assert_maps_to "docs/admin/security/audit-logs.md" "admin/security/audit-logs"
|
||||
assert_maps_to "docs/admin/groups.md" "admin/groups"
|
||||
assert_maps_to "docs/tutorials/best-practices/index.md" "tutorials/best-practices"
|
||||
|
||||
|
||||
+52
-2
@@ -1,2 +1,52 @@
|
||||
<!-- markdownlint-disable MD041 -->
|
||||
[https://coder.com/docs/about/contributing/CODE_OF_CONDUCT](https://coder.com/docs/about/contributing/CODE_OF_CONDUCT)
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to creating a positive environment include:
|
||||
|
||||
- Using welcoming and inclusive language
|
||||
- Being respectful of differing viewpoints and experiences
|
||||
- Gracefully accepting constructive criticism
|
||||
- Focusing on what is best for the community
|
||||
- Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
- The use of sexualized language or imagery and unwelcome sexual attention or advances
|
||||
- Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or electronic address, without explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Our Responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
|
||||
Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
|
||||
Representation of a project may be further defined and clarified by project maintainers.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at <opensource@coder.com>.
|
||||
All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
|
||||
The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
|
||||
Further details of specific enforcement policies may be posted separately.
|
||||
|
||||
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
|
||||
For answers to common questions about this code of conduct, see <https://www.contributor-covenant.org/faq>
|
||||
|
||||
+387
-2
@@ -1,2 +1,387 @@
|
||||
<!-- markdownlint-disable MD041 -->
|
||||
[https://coder.com/docs/about/contributing/CONTRIBUTING](https://coder.com/docs/about/contributing/CONTRIBUTING)
|
||||
# Contributing
|
||||
|
||||
Thank you for your interest in contributing to Coder.
|
||||
This guide covers how to set up a development environment, the day-to-day workflow, and what we expect from pull requests.
|
||||
All participation is governed by the [Code of Conduct](./CODE_OF_CONDUCT.md).
|
||||
|
||||
Area-specific guides live in [`contributing/`](./contributing/):
|
||||
|
||||
- [Backend](./contributing/backend.md): how the Go services fit together and how to test them.
|
||||
- [Frontend](./contributing/frontend.md): the React codebase and its conventions.
|
||||
- [Documentation](./contributing/documentation.md): the style guide for `docs/`.
|
||||
- [Modules](./contributing/modules.md) and [templates](./contributing/templates.md): contributing to the Coder Registry.
|
||||
- [AI contribution guidelines](./contributing/AI_CONTRIBUTING.md): rules for pull requests where an AI system is the primary author.
|
||||
|
||||
To report a security vulnerability, follow the [security policy](./SECURITY.md) instead of opening an issue.
|
||||
|
||||
## Requirements
|
||||
|
||||
To get started with Coder, the easiest way to set up the required environment is to use the provided [Nix environment](./flake.nix).
|
||||
Learn more [how Nix works](https://nixos.org/guides/how-nix-works).
|
||||
|
||||
### Nix
|
||||
|
||||
1. [Install Nix](https://nix.dev/install-nix#install-nix)
|
||||
|
||||
1. After you've installed Nix, instantiate the development with the `nix-shell`
|
||||
command:
|
||||
|
||||
```sh
|
||||
cd ~/code/coder
|
||||
|
||||
# https://nix.dev/tutorials/declarative-and-reproducible-developer-environments
|
||||
nix-shell
|
||||
|
||||
...
|
||||
copying path '/nix/store/3ms6cs5210n8vfb5a7jkdvzrzdagqzbp-iana-etc-20210225' from 'https://cache.nixos.org'...
|
||||
copying path '/nix/store/dxg5aijpyy36clz05wjsyk90gqcdzbam-iana-etc-20220520' from 'https://cache.nixos.org'...
|
||||
copying path '/nix/store/v2gvj8whv241nj4lzha3flq8pnllcmvv-ignore-5.2.0.tgz' from 'https://cache.nixos.org'...
|
||||
...
|
||||
```
|
||||
|
||||
1. Optional: If you have [direnv](https://direnv.net/) installed with
|
||||
[hooks configured](https://direnv.net/docs/hook.html), you can add `use nix`
|
||||
to `.envrc` to automatically instantiate the development environment:
|
||||
|
||||
```sh
|
||||
cd ~/code/coder
|
||||
echo "use nix" >.envrc
|
||||
direnv allow
|
||||
```
|
||||
|
||||
Now, whenever you enter the project folder,
|
||||
[`direnv`](https://direnv.net/docs/hook.html) will prepare the environment
|
||||
for you:
|
||||
|
||||
```sh
|
||||
cd ~/code/coder
|
||||
|
||||
direnv: loading ~/code/coder/.envrc
|
||||
direnv: using nix
|
||||
direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_BINTOOLS +NIX_BINTOOLS_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_BUILD_CORES +NIX_BUILD_TOP +NIX_CC +NIX_CC_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_CFLAGS_COMPILE +NIX_ENFORCE_NO_NATIVE +NIX_HARDENING_ENABLE +NIX_INDENT_MAKE +NIX_LDFLAGS +NIX_STORE +NM +NODE_PATH +OBJCOPY +OBJDUMP +RANLIB +READELF +SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +TEMP +TEMPDIR +TMP +TMPDIR +XDG_DATA_DIRS +buildInputs +buildPhase +builder +cmakeFlags +configureFlags +depsBuildBuild +depsBuildBuildPropagated +depsBuildTarget +depsBuildTargetPropagated +depsHostHost +depsHostHostPropagated +depsTargetTarget +depsTargetTargetPropagated +doCheck +doInstallCheck +mesonFlags +name +nativeBuildInputs +out +outputs +patches +phases +propagatedBuildInputs +propagatedNativeBuildInputs +shell +shellHook +stdenv +strictDeps +system ~PATH
|
||||
|
||||
🎉
|
||||
```
|
||||
|
||||
- If you encounter a `creating directory` error on macOS, check the
|
||||
[troubleshooting](#troubleshooting) section below.
|
||||
|
||||
### Without Nix
|
||||
|
||||
If you're not using the Nix environment, you can launch a local [DevContainer](./.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`, `mise`, and `make`.
|
||||
|
||||
For manual setup outside Nix and DevContainers, install Docker, `mise`, and
|
||||
`make`. Run `mise install` from the repository root to install Go, Node.js
|
||||
with `pnpm`, and development tools at the versions pinned in `mise.toml`.
|
||||
|
||||
## Development workflow
|
||||
|
||||
Use the following `make` 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`
|
||||
- `make pre-commit` runs gen, fmt, lint, typos, and builds a slim binary
|
||||
- `make pre-commit-light` runs fmt and lint for shell, terraform, markdown,
|
||||
helm, actions, and typos (skips gen, Go/TS lint+fmt, and binary build)
|
||||
- `make pre-push` runs heavier CI checks including tests (allowlisted)
|
||||
|
||||
Install the git hooks to run these automatically:
|
||||
|
||||
```sh
|
||||
git config core.hooksPath scripts/githooks
|
||||
```
|
||||
|
||||
Hook checks are opt-in. Enable them with `git config coder.pre-commit true`
|
||||
and `git config coder.pre-push true`; developers allowlisted in the hook
|
||||
scripts run them by default.
|
||||
|
||||
The hooks classify staged/changed files and select the appropriate target.
|
||||
Commits that only touch docs, shell, terraform, or other lightweight files
|
||||
run `make pre-commit-light` instead of the full `make pre-commit`, and
|
||||
`pre-push` is skipped entirely. Changes to Go, TypeScript, SQL, proto, or
|
||||
the Makefile trigger the full targets as before.
|
||||
|
||||
### Running Coder on development mode
|
||||
|
||||
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
|
||||
|
||||
Confirm that you're logged in by running:
|
||||
|
||||
```sh
|
||||
./scripts/coder-dev.sh list
|
||||
```
|
||||
|
||||
This should return an empty list of workspaces. If you encounter an error, review the output from the [develop.sh](./scripts/develop.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 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
|
||||
|
||||
You need to be a member or collaborator of the [coder](https://github.com/coder) GitHub organization to be able to deploy a PR.
|
||||
|
||||
You can test your changes by creating a PR deployment. There are two ways to do
|
||||
this:
|
||||
|
||||
- Run `./scripts/deploy-pr.sh`
|
||||
- Manually trigger the
|
||||
[`pr-deploy.yaml`](https://github.com/coder/coder/actions/workflows/pr-deploy.yaml)
|
||||
GitHub 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 we
|
||||
are intelligently checking if the image needs to be built)
|
||||
- `-e EXPERIMENT1,EXPERIMENT2` or `--experiments EXPERIMENT1,EXPERIMENT2`, will
|
||||
enable the specified experiments. (defaults to `*`)
|
||||
- `-n` or `--dry-run` will display the context without deployment. e.g., branch
|
||||
name and PR number, etc.
|
||||
- `-y` or `--yes`, will skip the CLI confirmation prompt.
|
||||
|
||||
> [!NOTE]
|
||||
> PR deployment will be re-deployed automatically when the PR is updated.
|
||||
> It will use the last values automatically for redeployment.
|
||||
|
||||
## Styling
|
||||
|
||||
- [Documentation style guide](./contributing/documentation.md)
|
||||
|
||||
- [Frontend styling guide](./contributing/frontend.md#styling)
|
||||
|
||||
## 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 like [Graphite](https://www.graphite.dev) 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 introduce
|
||||
a 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 from [Go's review philosophy](https://go.dev/doc/contribute#reviews).
|
||||
|
||||
Coder values thorough reviews. For each review comment that you receive, please
|
||||
"close" it by implementing the suggestion or providing an explanation on why the
|
||||
suggestion isn't the best option.
|
||||
Be sure to do this for each comment; you can select **Done** to indicate that you've implemented the suggestion, or you can add a comment explaining why you aren't implementing the suggestion (or what you chose to implement instead).
|
||||
|
||||
It is perfectly normal for changes to go through several rounds of reviews, with
|
||||
one or more reviewers making new comments every time, then waiting for an
|
||||
updated change before reviewing again. All contributors, including those from
|
||||
maintainers, are subject to the same review cycle; this process is not meant to
|
||||
be applied selectively or to discourage anyone from contributing.
|
||||
|
||||
## Releases
|
||||
|
||||
Coder releases are managed entirely through the
|
||||
[`release.yaml`](./.github/workflows/release.yaml)
|
||||
GitHub Actions workflow, triggered manually via "Run workflow" in the Actions
|
||||
tab. Release notes are automatically generated from commit titles and PR
|
||||
metadata.
|
||||
|
||||
### Release types
|
||||
|
||||
| Type | Tag | Source | Purpose |
|
||||
|------------------------|---------------|------------------|---------------------------------------|
|
||||
| RC (release candidate) | `vX.Y.0-rc.W` | `main` or branch | Pre-release for testing |
|
||||
| Create release branch | `vX.Y.0-rc.W` | `main` | Cut `release/X.Y` + tag RC atomically |
|
||||
| Release | `vX.Y.0` | `release/X.Y` | First release of a minor version |
|
||||
| Patch | `vX.Y.Z` | `release/X.Y` | Bug fixes and security patches |
|
||||
|
||||
### Workflow
|
||||
|
||||
RC tags can be created from `main` or from a release branch. The
|
||||
`create-release-branch` type creates `release/X.Y` and tags the next RC in one
|
||||
step, continuing the RC numbering sequence.
|
||||
|
||||
```txt
|
||||
main: --*--*--*--*--*--*--*--*--*--
|
||||
| rc.0 rc.1 |
|
||||
| +--- create-release-branch ---+
|
||||
| |
|
||||
| release/2.34: --*-- rc.2 -- rc.3 -- v2.34.0
|
||||
|
|
||||
+-- (more RCs on main for next cycle)
|
||||
```
|
||||
|
||||
1. **RC:** Go to [Actions > Release](https://github.com/coder/coder/actions/workflows/release.yaml),
|
||||
select "Run workflow", select `main` (or a release branch) from the "Use
|
||||
workflow from" dropdown, choose `rc`, and optionally provide a commit SHA
|
||||
(defaults to HEAD). The workflow calculates the next RC version
|
||||
automatically.
|
||||
2. **Create release branch:** Select `main` in the dropdown, choose
|
||||
`create-release-branch`, and optionally provide a commit SHA. This creates
|
||||
`release/X.Y` and tags the next RC atomically.
|
||||
3. **Release:** Select the release branch (e.g. `release/2.34`) from the
|
||||
dropdown and choose `release`. No other inputs needed.
|
||||
4. **Patch:** Cherry-pick fixes onto `release/X.Y`, select that branch from
|
||||
the dropdown, and choose `release`.
|
||||
|
||||
The workflow validates that commits are on the expected branch for each release
|
||||
type.
|
||||
|
||||
### Retrying a failed release
|
||||
|
||||
If the
|
||||
[`release.yaml`](https://github.com/coder/coder/actions/workflows/release.yaml)
|
||||
workflow fails after the tag has been pushed, re-run the failed jobs from the
|
||||
GitHub Actions UI. The `prepare-release` job is idempotent and will detect
|
||||
the existing tag.
|
||||
|
||||
To test the workflow without publishing, select dry-run.
|
||||
|
||||
### Commit messages
|
||||
|
||||
Commit messages should follow the
|
||||
[Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
|
||||
specification.
|
||||
|
||||
Allowed commit types (`feat`, `fix`, etc.) are listed in
|
||||
[conventional-commit-types](https://github.com/commitizen/conventional-commit-types/blob/c3a9be4c73e47f2e8197de775f41d981701407fb/index.json).
|
||||
Note that these types are also used to automatically sort and organize the
|
||||
release notes.
|
||||
|
||||
A good commit message title uses the imperative, present tense and is ~50
|
||||
characters long (no more than 72).
|
||||
|
||||
Examples:
|
||||
|
||||
- Good: `feat(coderd): add feature X`
|
||||
- Bad: `feat(coderd): added feature X` (past tense)
|
||||
|
||||
Scopes must reference a real path in the repository (a directory or file stem)
|
||||
and must contain all changed files. For example, use `coderd/database` if all
|
||||
changes are within that directory. If changes span multiple top-level
|
||||
directories, omit the scope.
|
||||
|
||||
A good rule of thumb for writing good commit messages is to recite:
|
||||
[If applied, this commit will ...](https://cbea.ms/git-commit/).
|
||||
|
||||
**Note:** We lint PR titles to ensure they follow the Conventional Commits
|
||||
specification, however, it's still possible to merge PRs on GitHub with a badly
|
||||
formatted title. Take care when merging single-commit PRs as GitHub may prefer
|
||||
to use the original commit title instead of the PR title.
|
||||
|
||||
### Backporting fixes to release branches
|
||||
|
||||
When a merged PR on `main` should also ship in older releases, add the
|
||||
`backport` label to the PR. The
|
||||
[backport workflow](./.github/workflows/backport.yaml)
|
||||
will automatically detect the latest three `release/*` branches,
|
||||
cherry-pick the merge commit onto each one, and open PRs for
|
||||
review.
|
||||
|
||||
The label can be added before or after the PR is merged. Each backport
|
||||
PR reuses the original title (e.g.
|
||||
`fix(site): correct button alignment (#12345)`) so the change is
|
||||
meaningful in release notes.
|
||||
|
||||
If the cherry-pick encounters conflicts, the backport PR is still created
|
||||
with instructions for manual resolution; no conflict markers are committed.
|
||||
|
||||
### Breaking changes
|
||||
|
||||
Breaking changes can be triggered in two ways:
|
||||
|
||||
- Add `!` to the commit message title, e.g.
|
||||
`feat(coderd)!: remove deprecated endpoint /test`
|
||||
- Add the
|
||||
[`release/breaking`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fbreaking)
|
||||
label to a PR that has, or will be, merged into `main`.
|
||||
|
||||
### Generative AI
|
||||
|
||||
Using AI to help with contributions is acceptable, but only if the [AI Contribution Guidelines](./contributing/AI_CONTRIBUTING.md)
|
||||
are followed. If most of your PR was generated by AI, please read and comply with these rules before submitting.
|
||||
|
||||
### Security
|
||||
|
||||
> [!CAUTION]
|
||||
> If you find a vulnerability, **DO NOT FILE AN ISSUE**. Instead, send an email
|
||||
> to <security@coder.com>.
|
||||
|
||||
The
|
||||
[`security`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Asecurity)
|
||||
label can be added to PRs that have, or will be, merged into `main`. Doing so
|
||||
will make sure the change stands out in the release notes.
|
||||
|
||||
### Experimental
|
||||
|
||||
The
|
||||
[`release/experimental`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fexperimental)
|
||||
label can be used to move the note to the bottom of the release notes under a
|
||||
separate title.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database migration mismatch after switching branches
|
||||
|
||||
If `./scripts/develop.sh` exits with a "database migration conflict" error,
|
||||
it means the database has migrations from another branch that don't exist
|
||||
on the current one. You have two options:
|
||||
|
||||
```sh
|
||||
# Roll back the mismatched migrations (preserves your dev data):
|
||||
./scripts/develop.sh --db-rollback
|
||||
|
||||
# Or wipe the database and start fresh:
|
||||
./scripts/develop.sh --db-reset
|
||||
```
|
||||
|
||||
### Nix on macOS: `error: creating directory`
|
||||
|
||||
On macOS, a [direnv bug](https://github.com/direnv/direnv/issues/1345) can cause
|
||||
`nix-shell` to fail to build or run `coder`. If you encounter
|
||||
`error: creating directory` when you attempt to run, build, or test, add a
|
||||
`mkdir` line to your `.envrc`:
|
||||
|
||||
```sh
|
||||
use nix
|
||||
mkdir -p "$TMPDIR"
|
||||
```
|
||||
|
||||
@@ -118,7 +118,7 @@ New integrations are always in progress. Open an issue to request one. Contribut
|
||||
## Contributing
|
||||
|
||||
New contributors are always welcome. If you are new to the Coder codebase, see
|
||||
[the contribution guide](https://coder.com/docs/about/contributing/CONTRIBUTING) to get started.
|
||||
[the contribution guide](https://github.com/coder/coder/blob/main/CONTRIBUTING.md) to get started.
|
||||
|
||||
## Hiring
|
||||
|
||||
|
||||
@@ -273,7 +273,7 @@ func TestMigrateUpWithFixtures(t *testing.T) {
|
||||
if len(emptyTables) > 0 {
|
||||
t.Log("The following tables have zero rows, consider adding fixtures for them or create a full database dump:")
|
||||
t.Errorf("tables have zero rows: %v", emptyTables)
|
||||
t.Log("See https://github.com/coder/coder/blob/main/docs/about/contributing/backend.md#database-fixtures-for-testing-migrations for more information")
|
||||
t.Log("See https://github.com/coder/coder/blob/main/contributing/backend.md#database-fixtures-for-testing-migrations for more information")
|
||||
}
|
||||
})
|
||||
|
||||
|
||||
@@ -1,9 +1,7 @@
|
||||
---
|
||||
title: AI Contribution Guidelines
|
||||
---
|
||||
# AI Contribution Guidelines
|
||||
|
||||
This document defines rules for contributions where an AI system is the primary author of the code (i.e., most of the pull request was generated by AI).
|
||||
It applies to all Coder repositories and is a supplement to the [existing contributing guidelines](./CONTRIBUTING.md), not a replacement.
|
||||
It applies to all Coder repositories and is a supplement to the [existing contributing guidelines](../CONTRIBUTING.md), not a replacement.
|
||||
|
||||
For minor AI-assisted edits, suggestions, or completions where the human contributor is clearly the primary author, these rules do not apply — standard contributing guidelines are sufficient.
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
title: Backend
|
||||
---
|
||||
# Backend
|
||||
|
||||
This guide is designed to support both Coder engineers and community contributors in understanding our backend systems and getting started with development.
|
||||
|
||||
@@ -18,9 +16,9 @@ Need help or have questions? Join the conversation on our [Discord server](https
|
||||
|
||||
To understand how the backend fits into the broader system, we recommend reviewing the following resources:
|
||||
|
||||
* [General Concepts](../../install/plan/sizing/index.md#general-concepts): Essential concepts and language used to describe how Coder is structured and operated.
|
||||
* [General Concepts](../docs/install/plan/sizing/index.md#general-concepts): Essential concepts and language used to describe how Coder is structured and operated.
|
||||
|
||||
* [Architecture](../../install/plan/architecture.md): A high-level overview of the infrastructure layout, key services, and how components interact.
|
||||
* [Architecture](../docs/install/plan/architecture.md): A high-level overview of the infrastructure layout, key services, and how components interact.
|
||||
|
||||
These sections provide the necessary context for navigating and contributing to the backend effectively.
|
||||
|
||||
@@ -51,78 +49,78 @@ Coder's backend is built using a collection of robust, modern Go libraries and i
|
||||
|
||||
The Coder backend is organized into multiple packages and directories, each with a specific purpose. Here's a high-level overview of the most important ones:
|
||||
|
||||
* [agent](../../../agent): core logic of a workspace agent, supports DevContainers, remote SSH, startup/shutdown script execution. Protobuf definitions for DRPC communication with `coderd` are kept in [proto](../../../agent/proto).
|
||||
* [cli](../../../cli): CLI interface for `coder` command built on [coder/serpent](https://github.com/coder/serpent). Input controls are defined in [cliui](../../../cli/cliui), and [testdata](../../../cli/testdata) contains golden files for common CLI calls
|
||||
* [cmd](../../../cmd): entry points for CLI and services, including `coderd`
|
||||
* [coderd](../../../coderd): the main API server implementation with [chi](https://github.com/go-chi/chi) endpoints
|
||||
* [audit](../../../coderd/audit): audit log logic, defines target resources, actions and extra fields
|
||||
* [autobuild](../../../coderd/autobuild): core logic of the workspace autobuild executor, periodically evaluates workspaces for next transition actions
|
||||
* [httpmw](../../../coderd/httpmw): HTTP middlewares mainly used to extract parameters from HTTP requests (e.g. current user, template, workspace, OAuth2 account, etc.) and storing them in the request context
|
||||
* [prebuilds](../../../coderd/prebuilds): common interfaces for prebuild workspaces, feature implementation is in [enterprise/prebuilds](../../../enterprise/coderd/prebuilds)
|
||||
* [provisionerdserver](../../../coderd/provisionerdserver): DRPC server for [provisionerd](../../../provisionerd) instances, used to validate and extract Terraform data and resources, and store them in the database.
|
||||
* [rbac](../../../coderd/rbac): RBAC engine for `coderd`, including authz layer, role definitions and custom roles. Built on top of [Open Policy Agent](https://github.com/open-policy-agent/opa) and Rego policies.
|
||||
* [telemetry](../../../coderd/telemetry): records a snapshot with various workspace data for telemetry purposes. Once recorded the reporter sends it to the configured telemetry endpoint.
|
||||
* [tracing](../../../coderd/tracing): extends telemetry with tracing data consistent with [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md)
|
||||
* [workspaceapps](../../../coderd/workspaceapps): core logic of a secure proxy to expose workspace apps deployed in a workspace
|
||||
* [wsbuilder](../../../coderd/wsbuilder): wrapper for business logic of creating a workspace build. It encapsulates all database operations required to insert a build record in a transaction.
|
||||
* [database](../../../coderd/database): schema migrations, query logic, in-memory database, etc.
|
||||
* [db2sdk](../../../coderd/database/db2sdk): translation between database structures and [codersdk](../../../codersdk) objects used by coderd API.
|
||||
* [dbauthz](../../../coderd/database/dbauthz): AuthZ wrappers for database queries, ideally, every query should verify first if the accessor is eligible to see the query results.
|
||||
* [dbfake](../../../coderd/database/dbfake): helper functions to quickly prepare the initial database state for testing purposes (e.g. create N healthy workspaces and templates), operates on higher level than [dbgen](../../../coderd/database/dbgen)
|
||||
* [dbgen](../../../coderd/database/dbgen): helper functions to insert raw records to the database store, used for testing purposes
|
||||
* [dbmock](../../../coderd/database/dbmock): a store wrapper for database queries, useful to verify if the function has been called, used for testing purposes
|
||||
* [dbpurge](../../../coderd/database/dbpurge): simple wrapper for periodic database cleanup operations
|
||||
* [migrations](../../../coderd/database/migrations): an ordered list of up/down database migrations, use `./create_migration.sh my_migration_name` to modify the database schema
|
||||
* [pubsub](../../../coderd/database/pubsub): PubSub implementation using PostgreSQL and in-memory drop-in replacement
|
||||
* [queries](../../../coderd/database/queries): contains SQL files with queries, `sqlc` compiles them to [Go functions](../../../coderd/database/queries.sql.go)
|
||||
* [sqlc.yaml](../../../coderd/database/sqlc.yaml): defines mappings between SQL types and custom Go structures
|
||||
* [codersdk](../../../codersdk): user-facing API entities used by CLI and site to communicate with `coderd` endpoints
|
||||
* [dogfood](../../../dogfood): build inputs for the images used by Coder's dogfood workspaces. The workspace templates that consume these images live in an internal Coder infrastructure repository.
|
||||
* [enterprise](../../../enterprise): enterprise-only features, notice similar file structure to repository root (`audit`, `cli`, `cmd`, `coderd`, etc.)
|
||||
* [coderd](../../../enterprise/coderd)
|
||||
* [prebuilds](../../../enterprise/coderd/prebuilds): core logic of prebuilt workspaces - reconciliation loop
|
||||
* [provisioner](../../../provisioner): supported implementation of provisioners, Terraform and "echo" (for testing purposes)
|
||||
* [provisionerd](../../../provisionerd): core logic of provisioner runner to interact provisionerd server, depending on a job acquired it calls template import, dry run or a workspace build
|
||||
* [pty](../../../pty): terminal emulation for agent shell
|
||||
* [support](../../../support): compile a support bundle with diagnostics
|
||||
* [tailnet](../../../tailnet): core logic of Tailnet controller to maintain DERP maps, coordinate connections with agents and peers
|
||||
* [vpn](../../../vpn): Coder Desktop (VPN) and tunneling components
|
||||
* [agent](../agent): core logic of a workspace agent, supports DevContainers, remote SSH, startup/shutdown script execution. Protobuf definitions for DRPC communication with `coderd` are kept in [proto](../agent/proto).
|
||||
* [cli](../cli): CLI interface for `coder` command built on [coder/serpent](https://github.com/coder/serpent). Input controls are defined in [cliui](../cli/cliui), and [testdata](../cli/testdata) contains golden files for common CLI calls
|
||||
* [cmd](../cmd): entry points for CLI and services, including `coderd`
|
||||
* [coderd](../coderd): the main API server implementation with [chi](https://github.com/go-chi/chi) endpoints
|
||||
* [audit](../coderd/audit): audit log logic, defines target resources, actions and extra fields
|
||||
* [autobuild](../coderd/autobuild): core logic of the workspace autobuild executor, periodically evaluates workspaces for next transition actions
|
||||
* [httpmw](../coderd/httpmw): HTTP middlewares mainly used to extract parameters from HTTP requests (e.g. current user, template, workspace, OAuth2 account, etc.) and storing them in the request context
|
||||
* [prebuilds](../coderd/prebuilds): common interfaces for prebuild workspaces, feature implementation is in [enterprise/prebuilds](../enterprise/coderd/prebuilds)
|
||||
* [provisionerdserver](../coderd/provisionerdserver): DRPC server for [provisionerd](../provisionerd) instances, used to validate and extract Terraform data and resources, and store them in the database.
|
||||
* [rbac](../coderd/rbac): RBAC engine for `coderd`, including authz layer, role definitions and custom roles. Built on top of [Open Policy Agent](https://github.com/open-policy-agent/opa) and Rego policies.
|
||||
* [telemetry](../coderd/telemetry): records a snapshot with various workspace data for telemetry purposes. Once recorded the reporter sends it to the configured telemetry endpoint.
|
||||
* [tracing](../coderd/tracing): extends telemetry with tracing data consistent with [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md)
|
||||
* [workspaceapps](../coderd/workspaceapps): core logic of a secure proxy to expose workspace apps deployed in a workspace
|
||||
* [wsbuilder](../coderd/wsbuilder): wrapper for business logic of creating a workspace build. It encapsulates all database operations required to insert a build record in a transaction.
|
||||
* [database](../coderd/database): schema migrations, query logic, in-memory database, etc.
|
||||
* [db2sdk](../coderd/database/db2sdk): translation between database structures and [codersdk](../codersdk) objects used by coderd API.
|
||||
* [dbauthz](../coderd/database/dbauthz): AuthZ wrappers for database queries, ideally, every query should verify first if the accessor is eligible to see the query results.
|
||||
* [dbfake](../coderd/database/dbfake): helper functions to quickly prepare the initial database state for testing purposes (e.g. create N healthy workspaces and templates), operates on higher level than [dbgen](../coderd/database/dbgen)
|
||||
* [dbgen](../coderd/database/dbgen): helper functions to insert raw records to the database store, used for testing purposes
|
||||
* [dbmock](../coderd/database/dbmock): a store wrapper for database queries, useful to verify if the function has been called, used for testing purposes
|
||||
* [dbpurge](../coderd/database/dbpurge): simple wrapper for periodic database cleanup operations
|
||||
* [migrations](../coderd/database/migrations): an ordered list of up/down database migrations, use `./create_migration.sh my_migration_name` to modify the database schema
|
||||
* [pubsub](../coderd/database/pubsub): PubSub implementation using PostgreSQL and in-memory drop-in replacement
|
||||
* [queries](../coderd/database/queries): contains SQL files with queries, `sqlc` compiles them to [Go functions](../coderd/database/queries.sql.go)
|
||||
* [sqlc.yaml](../coderd/database/sqlc.yaml): defines mappings between SQL types and custom Go structures
|
||||
* [codersdk](../codersdk): user-facing API entities used by CLI and site to communicate with `coderd` endpoints
|
||||
* [dogfood](../dogfood): build inputs for the images used by Coder's dogfood workspaces. The workspace templates that consume these images live in an internal Coder infrastructure repository.
|
||||
* [enterprise](../enterprise): enterprise-only features, notice similar file structure to repository root (`audit`, `cli`, `cmd`, `coderd`, etc.)
|
||||
* [coderd](../enterprise/coderd)
|
||||
* [prebuilds](../enterprise/coderd/prebuilds): core logic of prebuilt workspaces - reconciliation loop
|
||||
* [provisioner](../provisioner): supported implementation of provisioners, Terraform and "echo" (for testing purposes)
|
||||
* [provisionerd](../provisionerd): core logic of provisioner runner to interact provisionerd server, depending on a job acquired it calls template import, dry run or a workspace build
|
||||
* [pty](../pty): terminal emulation for agent shell
|
||||
* [support](../support): compile a support bundle with diagnostics
|
||||
* [tailnet](../tailnet): core logic of Tailnet controller to maintain DERP maps, coordinate connections with agents and peers
|
||||
* [vpn](../vpn): Coder Desktop (VPN) and tunneling components
|
||||
|
||||
## Testing
|
||||
|
||||
The Coder backend includes a rich suite of unit and end-to-end tests. A variety of helper utilities are used throughout the codebase to make testing easier, more consistent, and closer to real behavior.
|
||||
|
||||
### [clitest](../../../cli/clitest)
|
||||
### [clitest](../cli/clitest)
|
||||
|
||||
* Spawns an in-memory `serpent.Command` instance for unit testing
|
||||
* Configures an authorized `codersdk` client
|
||||
* Once a `serpent.Invocation` is created, tests can execute commands as if invoked by a real user
|
||||
|
||||
### [ptytest](../../../pty/ptytest)
|
||||
### [ptytest](../pty/ptytest)
|
||||
|
||||
* `ptytest` attaches to a `serpent.Invocation` and simulates TTY input/output
|
||||
* `pty` provides matchers and "write" operations for interacting with pseudo-terminals
|
||||
|
||||
### [coderdtest](../../../coderd/coderdtest)
|
||||
### [coderdtest](../coderd/coderdtest)
|
||||
|
||||
* Provides shortcuts to spin up an in-memory `coderd` instance
|
||||
* Can start an embedded provisioner daemon
|
||||
* Supports multi-user testing via `CreateFirstUser` and `CreateAnotherUser`
|
||||
* Includes "busy wait" helpers like `AwaitTemplateVersionJobCompleted`
|
||||
* [oidctest](../../../coderd/coderdtest/oidctest) can start a fake OIDC provider
|
||||
* [oidctest](../coderd/coderdtest/oidctest) can start a fake OIDC provider
|
||||
|
||||
### [testutil](../../../testutil)
|
||||
### [testutil](../testutil)
|
||||
|
||||
* General-purpose testing utilities, including:
|
||||
* [chan.go](../../../testutil/chan.go): helpers for sending/receiving objects from channels (`TrySend`, `RequireReceive`, etc.)
|
||||
* [duration.go](../../../testutil/duration.go): set timeouts for test execution
|
||||
* [eventually.go](../../../testutil/eventually.go): repeatedly poll for a condition using a ticker
|
||||
* [port.go](../../../testutil/port.go): select a free random port
|
||||
* [prometheus.go](../../../testutil/prometheus.go): validate Prometheus metrics with expected values
|
||||
* [pty.go](../../../testutil/pty.go): read output from a terminal until a condition is met
|
||||
* [wait_buffer.go](../../../testutil/wait_buffer.go): thread-safe `io.Writer` that blocks until accumulated output contains a signal (`WaitFor`, `WaitForNth`, `WaitForCond`)
|
||||
* [chan.go](../testutil/chan.go): helpers for sending/receiving objects from channels (`TrySend`, `RequireReceive`, etc.)
|
||||
* [duration.go](../testutil/duration.go): set timeouts for test execution
|
||||
* [eventually.go](../testutil/eventually.go): repeatedly poll for a condition using a ticker
|
||||
* [port.go](../testutil/port.go): select a free random port
|
||||
* [prometheus.go](../testutil/prometheus.go): validate Prometheus metrics with expected values
|
||||
* [pty.go](../testutil/pty.go): read output from a terminal until a condition is met
|
||||
* [wait_buffer.go](../testutil/wait_buffer.go): thread-safe `io.Writer` that blocks until accumulated output contains a signal (`WaitFor`, `WaitForNth`, `WaitForCond`)
|
||||
|
||||
### [dbtestutil](../../../coderd/database/dbtestutil)
|
||||
### [dbtestutil](../coderd/database/dbtestutil)
|
||||
|
||||
* Allows choosing between real and in-memory database backends for tests
|
||||
* `WillUsePostgres` is useful for skipping tests in CI environments that don't run Postgres
|
||||
@@ -171,9 +169,9 @@ 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)
|
||||
[`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
|
||||
* Full database dumps
|
||||
[`migrations/testdata/full_dumps`](../../../coderd/database/migrations/testdata/full_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
|
||||
@@ -196,7 +194,7 @@ To add a new partial fixture, run the following command:
|
||||
```
|
||||
|
||||
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)
|
||||
[`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
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
title: Documentation
|
||||
---
|
||||
# Documentation
|
||||
|
||||
This style guide is primarily for use with authoring documentation.
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
title: Frontend
|
||||
---
|
||||
# Frontend
|
||||
|
||||
Welcome to the guide for contributing to the Coder frontend. Whether you’re part
|
||||
of the community or a Coder team member, this documentation will help you get
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
title: Contribute modules
|
||||
---
|
||||
# Contribute modules
|
||||
|
||||
Learn how to create and contribute Terraform modules to the Coder Registry. Modules provide reusable components that extend Coder workspaces with IDEs, development tools, login tools, and other features.
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
title: Contribute templates
|
||||
---
|
||||
# Contribute templates
|
||||
|
||||
Learn how to create and contribute complete Coder workspace templates to the Coder Registry. Templates provide ready-to-use workspace configurations that users can deploy directly to create development environments.
|
||||
|
||||
@@ -175,13 +175,13 @@ This guide is itself exempt from the Coder rules: it demonstrates the violations
|
||||
Zero baseline is measured over `docs/` excluding `docs/.style/style-guide/`.
|
||||
Run `make lint/prose` to reproduce the baseline locally.
|
||||
|
||||
## Relationship to `docs/about/contributing/documentation.md`
|
||||
## Relationship to `contributing/documentation.md`
|
||||
|
||||
A public-facing prose summary lives today at [`docs/about/contributing/documentation.md`](../../about/contributing/documentation.md).
|
||||
A follow-up PR will redirect that page to this guide.
|
||||
A public-facing prose summary lives today at [`contributing/documentation.md`](https://github.com/coder/coder/blob/main/contributing/documentation.md) in the repository.
|
||||
A follow-up PR will fold that page into this guide.
|
||||
Until then, follow the public summary for anything the subpages of this guide don't cover.
|
||||
New prose rules land here.
|
||||
The public page is frozen pending the redirect.
|
||||
The public page is frozen pending that move.
|
||||
|
||||
## Third-party references
|
||||
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
title: Contributor Covenant Code of Conduct
|
||||
---
|
||||
|
||||
## Our Pledge
|
||||
|
||||
In the interest of fostering an open and welcoming environment, we as
|
||||
contributors and maintainers pledge to making participation in our project and
|
||||
our community a harassment-free experience for everyone, regardless of age, body
|
||||
size, disability, ethnicity, sex characteristics, gender identity and
|
||||
expression, level of experience, education, socio-economic status, nationality,
|
||||
personal appearance, race, religion, or sexual identity and orientation.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to creating a positive environment
|
||||
include:
|
||||
|
||||
- Using welcoming and inclusive language
|
||||
- Being respectful of differing viewpoints and experiences
|
||||
- Gracefully accepting constructive criticism
|
||||
- Focusing on what is best for the community
|
||||
- Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
- The use of sexualized language or imagery and unwelcome sexual attention or
|
||||
advances
|
||||
- Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or electronic
|
||||
address, without explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
|
||||
## Our Responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable
|
||||
behavior and are expected to take appropriate and fair corrective action in
|
||||
response to any instances of unacceptable behavior.
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject
|
||||
comments, commits, code, wiki edits, issues, and other contributions that are
|
||||
not aligned to this Code of Conduct, or to ban temporarily or permanently any
|
||||
contributor for other behaviors that they deem inappropriate, threatening,
|
||||
offensive, or harmful.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies both within project spaces and in public spaces
|
||||
when an individual is representing the project or its community. Examples of
|
||||
representing a project or community include using an official project e-mail
|
||||
address, posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event. Representation of a project may be
|
||||
further defined and clarified by project maintainers.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported by contacting the project team at <opensource@coder.com>. All complaints
|
||||
will be reviewed and investigated and will result in a response that is deemed
|
||||
necessary and appropriate to the circumstances. The project team is obligated to
|
||||
maintain confidentiality with regard to the reporter of an incident. Further
|
||||
details of specific enforcement policies may be posted separately.
|
||||
|
||||
Project maintainers who do not follow or enforce the Code of Conduct in good
|
||||
faith may face temporary or permanent repercussions as determined by other
|
||||
members of the project's leadership.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
||||
version 1.4, available at
|
||||
<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
|
||||
For answers to common questions about this code of conduct, see
|
||||
<https://www.contributor-covenant.org/faq>
|
||||
@@ -1,379 +0,0 @@
|
||||
---
|
||||
title: Contributing
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
<div class="tabs">
|
||||
|
||||
To get started with Coder, the easiest way to set up the required environment is to use the provided [Nix environment](../../../flake.nix).
|
||||
Learn more [how Nix works](https://nixos.org/guides/how-nix-works).
|
||||
|
||||
### Nix
|
||||
|
||||
1. [Install Nix](https://nix.dev/install-nix#install-nix)
|
||||
|
||||
1. After you've installed Nix, instantiate the development with the `nix-shell`
|
||||
command:
|
||||
|
||||
```sh
|
||||
cd ~/code/coder
|
||||
|
||||
# https://nix.dev/tutorials/declarative-and-reproducible-developer-environments
|
||||
nix-shell
|
||||
|
||||
...
|
||||
copying path '/nix/store/3ms6cs5210n8vfb5a7jkdvzrzdagqzbp-iana-etc-20210225' from 'https://cache.nixos.org'...
|
||||
copying path '/nix/store/dxg5aijpyy36clz05wjsyk90gqcdzbam-iana-etc-20220520' from 'https://cache.nixos.org'...
|
||||
copying path '/nix/store/v2gvj8whv241nj4lzha3flq8pnllcmvv-ignore-5.2.0.tgz' from 'https://cache.nixos.org'...
|
||||
...
|
||||
```
|
||||
|
||||
1. Optional: If you have [direnv](https://direnv.net/) installed with
|
||||
[hooks configured](https://direnv.net/docs/hook.html), you can add `use nix`
|
||||
to `.envrc` to automatically instantiate the development environment:
|
||||
|
||||
```sh
|
||||
cd ~/code/coder
|
||||
echo "use nix" >.envrc
|
||||
direnv allow
|
||||
```
|
||||
|
||||
Now, whenever you enter the project folder,
|
||||
[`direnv`](https://direnv.net/docs/hook.html) will prepare the environment
|
||||
for you:
|
||||
|
||||
```sh
|
||||
cd ~/code/coder
|
||||
|
||||
direnv: loading ~/code/coder/.envrc
|
||||
direnv: using nix
|
||||
direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_BINTOOLS +NIX_BINTOOLS_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_BUILD_CORES +NIX_BUILD_TOP +NIX_CC +NIX_CC_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_CFLAGS_COMPILE +NIX_ENFORCE_NO_NATIVE +NIX_HARDENING_ENABLE +NIX_INDENT_MAKE +NIX_LDFLAGS +NIX_STORE +NM +NODE_PATH +OBJCOPY +OBJDUMP +RANLIB +READELF +SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +TEMP +TEMPDIR +TMP +TMPDIR +XDG_DATA_DIRS +buildInputs +buildPhase +builder +cmakeFlags +configureFlags +depsBuildBuild +depsBuildBuildPropagated +depsBuildTarget +depsBuildTargetPropagated +depsHostHost +depsHostHostPropagated +depsTargetTarget +depsTargetTargetPropagated +doCheck +doInstallCheck +mesonFlags +name +nativeBuildInputs +out +outputs +patches +phases +propagatedBuildInputs +propagatedNativeBuildInputs +shell +shellHook +stdenv +strictDeps +system ~PATH
|
||||
|
||||
🎉
|
||||
```
|
||||
|
||||
- If you encounter a `creating directory` error on macOS, check the
|
||||
[troubleshooting](#troubleshooting) section below.
|
||||
|
||||
### Without Nix
|
||||
|
||||
If you're not using the Nix environment, you can launch a local [DevContainer](../../../.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`, `mise`, and `make`.
|
||||
|
||||
For manual setup outside Nix and DevContainers, install Docker, `mise`, and
|
||||
`make`. Run `mise install` from the repository root to install Go, Node.js
|
||||
with `pnpm`, and development tools at the versions pinned in `mise.toml`.
|
||||
|
||||
</div>
|
||||
|
||||
## Development workflow
|
||||
|
||||
Use the following `make` 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`
|
||||
- `make pre-commit` runs gen, fmt, lint, typos, and builds a slim binary
|
||||
- `make pre-commit-light` runs fmt and lint for shell, terraform, markdown,
|
||||
helm, actions, and typos (skips gen, Go/TS lint+fmt, and binary build)
|
||||
- `make pre-push` runs heavier CI checks including tests (allowlisted)
|
||||
|
||||
Install the git hooks to run these automatically:
|
||||
|
||||
```sh
|
||||
git config core.hooksPath scripts/githooks
|
||||
```
|
||||
|
||||
Hook checks are opt-in. Enable them with `git config coder.pre-commit true`
|
||||
and `git config coder.pre-push true`; developers allowlisted in the hook
|
||||
scripts run them by default.
|
||||
|
||||
The hooks classify staged/changed files and select the appropriate target.
|
||||
Commits that only touch docs, shell, terraform, or other lightweight files
|
||||
run `make pre-commit-light` instead of the full `make pre-commit`, and
|
||||
`pre-push` is skipped entirely. Changes to Go, TypeScript, SQL, proto, or
|
||||
the Makefile trigger the full targets as before.
|
||||
|
||||
### Running Coder on development mode
|
||||
|
||||
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
|
||||
|
||||
Confirm that you're logged in by running:
|
||||
|
||||
```sh
|
||||
./scripts/coder-dev.sh list
|
||||
```
|
||||
|
||||
This should return an empty list of workspaces. If you encounter an error, review the output from the [develop.sh](../../../scripts/develop.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 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
|
||||
|
||||
You need to be a member or collaborator of the [coder](https://github.com/coder) GitHub organization to be able to deploy a PR.
|
||||
|
||||
You can test your changes by creating a PR deployment. There are two ways to do
|
||||
this:
|
||||
|
||||
- Run `./scripts/deploy-pr.sh`
|
||||
- Manually trigger the
|
||||
[`pr-deploy.yaml`](https://github.com/coder/coder/actions/workflows/pr-deploy.yaml)
|
||||
GitHub 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 we
|
||||
are intelligently checking if the image needs to be built)
|
||||
- `-e EXPERIMENT1,EXPERIMENT2` or `--experiments EXPERIMENT1,EXPERIMENT2`, will
|
||||
enable the specified experiments. (defaults to `*`)
|
||||
- `-n` or `--dry-run` will display the context without deployment. e.g., branch
|
||||
name and PR number, etc.
|
||||
- `-y` or `--yes`, will skip the CLI confirmation prompt.
|
||||
|
||||
> [!NOTE]
|
||||
> PR deployment will be re-deployed automatically when the PR is updated.
|
||||
> It will use the last values automatically for redeployment.
|
||||
|
||||
## Styling
|
||||
|
||||
- [Documentation style guide](./documentation.md)
|
||||
|
||||
- [Frontend styling guide](./frontend.md#styling)
|
||||
|
||||
## 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 like [Graphite](https://www.graphite.dev) 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 introduce
|
||||
a 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 from [Go's review philosophy](https://go.dev/doc/contribute#reviews).
|
||||
|
||||
Coder values thorough reviews. For each review comment that you receive, please
|
||||
"close" it by implementing the suggestion or providing an explanation on why the
|
||||
suggestion isn't the best option.
|
||||
Be sure to do this for each comment; you can select **Done** to indicate that you've implemented the suggestion, or you can add a comment explaining why you aren't implementing the suggestion (or what you chose to implement instead).
|
||||
|
||||
It is perfectly normal for changes to go through several rounds of reviews, with
|
||||
one or more reviewers making new comments every time, then waiting for an
|
||||
updated change before reviewing again. All contributors, including those from
|
||||
maintainers, are subject to the same review cycle; this process is not meant to
|
||||
be applied selectively or to discourage anyone from contributing.
|
||||
|
||||
## Releases
|
||||
|
||||
Coder releases are managed entirely through the
|
||||
[`release.yaml`](../../../.github/workflows/release.yaml)
|
||||
GitHub Actions workflow, triggered manually via "Run workflow" in the Actions
|
||||
tab. Release notes are automatically generated from commit titles and PR
|
||||
metadata.
|
||||
|
||||
### Release types
|
||||
|
||||
| Type | Tag | Source | Purpose |
|
||||
|------------------------|---------------|------------------|---------------------------------------|
|
||||
| RC (release candidate) | `vX.Y.0-rc.W` | `main` or branch | Pre-release for testing |
|
||||
| Create release branch | `vX.Y.0-rc.W` | `main` | Cut `release/X.Y` + tag RC atomically |
|
||||
| Release | `vX.Y.0` | `release/X.Y` | First release of a minor version |
|
||||
| Patch | `vX.Y.Z` | `release/X.Y` | Bug fixes and security patches |
|
||||
|
||||
### Workflow
|
||||
|
||||
RC tags can be created from `main` or from a release branch. The
|
||||
`create-release-branch` type creates `release/X.Y` and tags the next RC in one
|
||||
step, continuing the RC numbering sequence.
|
||||
|
||||
```txt
|
||||
main: --*--*--*--*--*--*--*--*--*--
|
||||
| rc.0 rc.1 |
|
||||
| +--- create-release-branch ---+
|
||||
| |
|
||||
| release/2.34: --*-- rc.2 -- rc.3 -- v2.34.0
|
||||
|
|
||||
+-- (more RCs on main for next cycle)
|
||||
```
|
||||
|
||||
1. **RC:** Go to [Actions > Release](https://github.com/coder/coder/actions/workflows/release.yaml),
|
||||
select "Run workflow", select `main` (or a release branch) from the "Use
|
||||
workflow from" dropdown, choose `rc`, and optionally provide a commit SHA
|
||||
(defaults to HEAD). The workflow calculates the next RC version
|
||||
automatically.
|
||||
2. **Create release branch:** Select `main` in the dropdown, choose
|
||||
`create-release-branch`, and optionally provide a commit SHA. This creates
|
||||
`release/X.Y` and tags the next RC atomically.
|
||||
3. **Release:** Select the release branch (e.g. `release/2.34`) from the
|
||||
dropdown and choose `release`. No other inputs needed.
|
||||
4. **Patch:** Cherry-pick fixes onto `release/X.Y`, select that branch from
|
||||
the dropdown, and choose `release`.
|
||||
|
||||
The workflow validates that commits are on the expected branch for each release
|
||||
type.
|
||||
|
||||
### Retrying a failed release
|
||||
|
||||
If the
|
||||
[`release.yaml`](https://github.com/coder/coder/actions/workflows/release.yaml)
|
||||
workflow fails after the tag has been pushed, re-run the failed jobs from the
|
||||
GitHub Actions UI. The `prepare-release` job is idempotent and will detect
|
||||
the existing tag.
|
||||
|
||||
To test the workflow without publishing, select dry-run.
|
||||
|
||||
### Commit messages
|
||||
|
||||
Commit messages should follow the
|
||||
[Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
|
||||
specification.
|
||||
|
||||
Allowed commit types (`feat`, `fix`, etc.) are listed in
|
||||
[conventional-commit-types](https://github.com/commitizen/conventional-commit-types/blob/c3a9be4c73e47f2e8197de775f41d981701407fb/index.json).
|
||||
Note that these types are also used to automatically sort and organize the
|
||||
release notes.
|
||||
|
||||
A good commit message title uses the imperative, present tense and is ~50
|
||||
characters long (no more than 72).
|
||||
|
||||
Examples:
|
||||
|
||||
- Good: `feat(coderd): add feature X`
|
||||
- Bad: `feat(coderd): added feature X` (past tense)
|
||||
|
||||
Scopes must reference a real path in the repository (a directory or file stem)
|
||||
and must contain all changed files. For example, use `coderd/database` if all
|
||||
changes are within that directory. If changes span multiple top-level
|
||||
directories, omit the scope.
|
||||
|
||||
A good rule of thumb for writing good commit messages is to recite:
|
||||
[If applied, this commit will ...](https://cbea.ms/git-commit/).
|
||||
|
||||
**Note:** We lint PR titles to ensure they follow the Conventional Commits
|
||||
specification, however, it's still possible to merge PRs on GitHub with a badly
|
||||
formatted title. Take care when merging single-commit PRs as GitHub may prefer
|
||||
to use the original commit title instead of the PR title.
|
||||
|
||||
### Backporting fixes to release branches
|
||||
|
||||
When a merged PR on `main` should also ship in older releases, add the
|
||||
`backport` label to the PR. The
|
||||
[backport workflow](../../../.github/workflows/backport.yaml)
|
||||
will automatically detect the latest three `release/*` branches,
|
||||
cherry-pick the merge commit onto each one, and open PRs for
|
||||
review.
|
||||
|
||||
The label can be added before or after the PR is merged. Each backport
|
||||
PR reuses the original title (e.g.
|
||||
`fix(site): correct button alignment (#12345)`) so the change is
|
||||
meaningful in release notes.
|
||||
|
||||
If the cherry-pick encounters conflicts, the backport PR is still created
|
||||
with instructions for manual resolution; no conflict markers are committed.
|
||||
|
||||
### Breaking changes
|
||||
|
||||
Breaking changes can be triggered in two ways:
|
||||
|
||||
- Add `!` to the commit message title, e.g.
|
||||
`feat(coderd)!: remove deprecated endpoint /test`
|
||||
- Add the
|
||||
[`release/breaking`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fbreaking)
|
||||
label to a PR that has, or will be, merged into `main`.
|
||||
|
||||
### Generative AI
|
||||
|
||||
Using AI to help with contributions is acceptable, but only if the [AI Contribution Guidelines](./AI_CONTRIBUTING.md)
|
||||
are followed. If most of your PR was generated by AI, please read and comply with these rules before submitting.
|
||||
|
||||
### Security
|
||||
|
||||
> [!CAUTION]
|
||||
> If you find a vulnerability, **DO NOT FILE AN ISSUE**. Instead, send an email
|
||||
> to <security@coder.com>.
|
||||
|
||||
The
|
||||
[`security`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Asecurity)
|
||||
label can be added to PRs that have, or will be, merged into `main`. Doing so
|
||||
will make sure the change stands out in the release notes.
|
||||
|
||||
### Experimental
|
||||
|
||||
The
|
||||
[`release/experimental`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fexperimental)
|
||||
label can be used to move the note to the bottom of the release notes under a
|
||||
separate title.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database migration mismatch after switching branches
|
||||
|
||||
If `./scripts/develop.sh` exits with a "database migration conflict" error,
|
||||
it means the database has migrations from another branch that don't exist
|
||||
on the current one. You have two options:
|
||||
|
||||
```sh
|
||||
# Roll back the mismatched migrations (preserves your dev data):
|
||||
./scripts/develop.sh --db-rollback
|
||||
|
||||
# Or wipe the database and start fresh:
|
||||
./scripts/develop.sh --db-reset
|
||||
```
|
||||
|
||||
### Nix on macOS: `error: creating directory`
|
||||
|
||||
On macOS, a [direnv bug](https://github.com/direnv/direnv/issues/1345) can cause
|
||||
`nix-shell` to fail to build or run `coder`. If you encounter
|
||||
`error: creating directory` when you attempt to run, build, or test, add a
|
||||
`mkdir` line to your `.envrc`:
|
||||
|
||||
```sh
|
||||
use nix
|
||||
mkdir -p "$TMPDIR"
|
||||
```
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
title: Security policy
|
||||
---
|
||||
|
||||
Coder welcomes feedback from security researchers and the general public to help improve our security.
|
||||
If you believe you have discovered a vulnerability, privacy issue, exposed data, or other security issues
|
||||
in any of our assets, we want to hear from you.
|
||||
|
||||
If you find a vulnerability, **DO NOT FILE AN ISSUE**.
|
||||
Instead, send an email to
|
||||
<security@coder.com>.
|
||||
|
||||
Refer to the [Security policy](https://coder.com/security/policy) for more information.
|
||||
@@ -1,4 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="none" viewBox="0 0 20 20">
|
||||
<path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 2.5v10m10-5a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5Zm-10 10a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5Z"/>
|
||||
<path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 7.5A7.5 7.5 0 0 1 7.5 15"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 428 B |
@@ -23,62 +23,6 @@
|
||||
"path": "./support/support-bundle.md"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Contributing",
|
||||
"description": "Set up your development environment and learn the workflow for contributing code to Coder.",
|
||||
"path": "./about/contributing/CONTRIBUTING.md",
|
||||
"icon_path": "./images/icons/contributing.svg",
|
||||
"children": [
|
||||
{
|
||||
"title": "Code of Conduct",
|
||||
"description": "Read the Contributor Covenant code of conduct that governs participation in the Coder community.",
|
||||
"path": "./about/contributing/CODE_OF_CONDUCT.md",
|
||||
"icon_path": "./images/icons/circle-dot.svg"
|
||||
},
|
||||
{
|
||||
"title": "Documentation",
|
||||
"description": "Follow Coder's style guide conventions for voice, formatting, and terminology when you author documentation.",
|
||||
"path": "./about/contributing/documentation.md",
|
||||
"icon_path": "./images/icons/document.svg"
|
||||
},
|
||||
{
|
||||
"title": "Modules",
|
||||
"description": "Learn how to build and contribute reusable Terraform modules to the Coder Registry.",
|
||||
"path": "./about/contributing/modules.md",
|
||||
"icon_path": "./images/icons/gear.svg"
|
||||
},
|
||||
{
|
||||
"title": "Templates",
|
||||
"description": "Learn how to build and contribute complete workspace templates to the Coder Registry.",
|
||||
"path": "./about/contributing/templates.md",
|
||||
"icon_path": "./images/icons/picture.svg"
|
||||
},
|
||||
{
|
||||
"title": "Backend",
|
||||
"description": "A guide to Coder's backend systems to help engineers and community contributors start backend development.",
|
||||
"path": "./about/contributing/backend.md",
|
||||
"icon_path": "./images/icons/gear.svg"
|
||||
},
|
||||
{
|
||||
"title": "Frontend",
|
||||
"description": "A guide to Coder's frontend codebase and conventions to help you start contributing to the UI.",
|
||||
"path": "./about/contributing/frontend.md",
|
||||
"icon_path": "./images/icons/frontend.svg"
|
||||
},
|
||||
{
|
||||
"title": "Security",
|
||||
"description": "Read Coder's security policy and learn how to responsibly report a security vulnerability.",
|
||||
"path": "./about/contributing/SECURITY.md",
|
||||
"icon_path": "./images/icons/lock.svg"
|
||||
},
|
||||
{
|
||||
"title": "AI Contribution Guidelines",
|
||||
"description": "Follow the rules for pull requests where an AI system is the primary author of the code.",
|
||||
"path": "./about/contributing/AI_CONTRIBUTING.md",
|
||||
"icon_path": "./images/icons/ai_intelligence.svg"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -110,7 +110,7 @@ For support, consult our knowledgeable and growing community on
|
||||
already. Customers with a valid Coder license, can submit a support request or
|
||||
contact your [account team](https://coder.com/contact).
|
||||
|
||||
We intend [Coder documentation](../about/contributing/documentation.md) to be the
|
||||
We intend [Coder documentation](https://github.com/coder/coder/blob/main/contributing/documentation.md) to be the
|
||||
[single source of truth](https://en.wikipedia.org/wiki/Single_source_of_truth)
|
||||
and all features should have some form of complete documentation that outlines
|
||||
how to use or implement a feature. If you discover an error or if you have a
|
||||
|
||||
@@ -16,7 +16,7 @@ repository.
|
||||
|
||||
## Content
|
||||
|
||||
Defer to our [Contributing/Documentation](../about/contributing/documentation.md) page
|
||||
Defer to our [documentation style guide](https://github.com/coder/coder/blob/main/contributing/documentation.md) page
|
||||
for rules on technical writing.
|
||||
|
||||
### Adding Photos
|
||||
|
||||
@@ -10,7 +10,7 @@ as `make lint/docs-html` (part of `make lint`).
|
||||
`<region>` or `<server>__` is parsed as an unknown HTML tag and stripped from
|
||||
the rendered page, so readers see broken text. Wrap placeholders in backticks
|
||||
so they render as inline code (see
|
||||
[`docs/about/contributing/documentation.md`](../../docs/about/contributing/documentation.md#placeholders-in-angle-brackets)).
|
||||
[`contributing/documentation.md`](../../contributing/documentation.md#placeholders-in-angle-brackets)).
|
||||
This also covers CLI `--help` strings and Swagger annotations, whose text is
|
||||
generated into `docs/reference/**`.
|
||||
- **Void-element end tags** such as `</br>`. Void elements like `<br>`, `<img>`,
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
// - Swallowed angle-bracket placeholders. An unwrapped placeholder such as
|
||||
// <region> or <server>__ is parsed as an unknown HTML tag and stripped
|
||||
// from the rendered page, so readers see broken text. Placeholders must be
|
||||
// wrapped in backticks (see docs/about/contributing/documentation.md).
|
||||
// wrapped in backticks (see contributing/documentation.md).
|
||||
// This also covers CLI --help strings and Swagger annotations, whose text
|
||||
// is generated into docs/reference/**.
|
||||
// - Structurally invalid or unregistered HTML: end tags for void elements
|
||||
@@ -218,7 +218,7 @@ func run(roots []string, stdout, stderr io.Writer) int {
|
||||
if htmlIssues > 0 {
|
||||
_, _ = fmt.Fprintf(stderr, "\ndocshtmlcheck: found %d invalid inline HTML issue(s).\n"+
|
||||
"Wrap angle-bracket placeholders in backticks so they render as inline code\n"+
|
||||
"(see docs/about/contributing/documentation.md), fix void-element end tags\n"+
|
||||
"(see contributing/documentation.md), fix void-element end tags\n"+
|
||||
"like </br>, use registered components for custom tags, and close container tags.\n", htmlIssues)
|
||||
}
|
||||
if staleIssues > 0 {
|
||||
|
||||
Reference in New Issue
Block a user