diff --git a/docs/about/contributing/CONTRIBUTING.md b/docs/about/contributing/CONTRIBUTING.md index 98243d3790f77..7b289517336b8 100644 --- a/docs/about/contributing/CONTRIBUTING.md +++ b/docs/about/contributing/CONTRIBUTING.md @@ -148,6 +148,32 @@ channel. - [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).