From a53f1b2d0a647cb8351e9d3db40fd75851252645 Mon Sep 17 00:00:00 2001 From: Spike Curtis Date: Thu, 4 Sep 2025 07:59:21 +0000 Subject: [PATCH 1/2] docs: add guidelines about PR size --- docs/about/contributing/CONTRIBUTING.md | 26 +++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/about/contributing/CONTRIBUTING.md b/docs/about/contributing/CONTRIBUTING.md index 98243d3790f77..56a6037b4e73c 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. + 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 back compatibility issues, even if a later PR 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). From 86d0b4834b8f1b403d1718f684b532aaf877f4bf Mon Sep 17 00:00:00 2001 From: Spike Curtis Date: Thu, 4 Sep 2025 09:31:40 +0000 Subject: [PATCH 2/2] fix hyphenation, nits --- docs/about/contributing/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/about/contributing/CONTRIBUTING.md b/docs/about/contributing/CONTRIBUTING.md index 56a6037b4e73c..7b289517336b8 100644 --- a/docs/about/contributing/CONTRIBUTING.md +++ b/docs/about/contributing/CONTRIBUTING.md @@ -154,11 +154,11 @@ We welcome pull requests (PRs) from community members including (but not limited 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.) +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. + 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. @@ -167,7 +167,7 @@ Stacking tools like [Graphite](https://www.graphite.dev) are useful for keeping Each PR: - Must individually build and pass all tests, including formatting and linting. -- Must not introduce regressions or back compatibility issues, even if a later PR would resolve the issue. +- 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