From 2ad11d1e5a6348cb48fe82ed4728734655109e35 Mon Sep 17 00:00:00 2001 From: Lucky Ivanius Date: Fri, 2 May 2025 10:37:40 +0700 Subject: [PATCH 1/6] docs: update PR naming guidelines --- .github/CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f586a76..2c84f33 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -168,8 +168,10 @@ We are using commits (PR names) to communicate the release log to all stakeholde Thus, the names of the PRs must: 1. be oriented toward the end users -1. follow [Conventional Commits Guidelines](https://www.conventionalcommits.org) -1. be [clean and simple](https://pulsar.apache.org/contribute/develop-semantic-title/#how-to-write-good-pr-titles) +2. follow [Conventional Commits Guidelines](https://www.conventionalcommits.org) +3. be [clean and simple](https://pulsar.apache.org/contribute/develop-semantic-title/#how-to-write-good-pr-titles) +4. be written from a user's perspective (what the user gets) +5. use present tense to describe the change ``` // Good examples: @@ -183,6 +185,35 @@ Thus, the names of the PRs must: - feat: modified door function ``` +> [!IMPORTANT] +> When naming PRs, focus on describing the user capability (what they can do) rather than the technical implementation (how it's done): +> +> Compare these examples: +> - ❌ "quick custom subscribe button" - describes an object +> - ✅ "customize subscription preferences" - describes user capability +> +> Think of it this way: +> - A button isn't a feature; what it enables users to do is the feature +> - A toggle isn't a feature; the control it gives users is the feature +> - A handler isn't a feature; the functionality it provides is the feature +> +> Always ask yourself: "What will users be able to do?" instead of "What am I building?" + +The key differences are: + +1. Good examples focus on user capabilities: + - "enable music playback control" instead of "add play button" + - "prevent sound during mute state" instead of "add mute toggle" + - Each name describes what users can accomplish + +2. Bad examples focus on technical implementation: + - "subscribe button" - just names a UI element + - "add mute toggle" - describes a component + - "modify door handler" - describes code changes + - None of these tell users what they can actually do + +This makes it immediately clear that PR names should describe features from the user's perspective rather than the technical components used to implement them. + ## Requesting Review Once your PR is ready, assign reviewers and mark it as "ready to review." But before that, report the time you have spent on it. From 29d7c42e159d8ed45c4931c7af2473aeedcc439a Mon Sep 17 00:00:00 2001 From: Lucky Ivanius Date: Fri, 2 May 2025 18:12:23 +0700 Subject: [PATCH 2/6] docs: fix numbering in CONTRIBUTING.md --- .github/CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 2c84f33..e85284e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -168,10 +168,10 @@ We are using commits (PR names) to communicate the release log to all stakeholde Thus, the names of the PRs must: 1. be oriented toward the end users -2. follow [Conventional Commits Guidelines](https://www.conventionalcommits.org) -3. be [clean and simple](https://pulsar.apache.org/contribute/develop-semantic-title/#how-to-write-good-pr-titles) -4. be written from a user's perspective (what the user gets) -5. use present tense to describe the change +1. follow [Conventional Commits Guidelines](https://www.conventionalcommits.org) +1. be [clean and simple](https://pulsar.apache.org/contribute/develop-semantic-title/#how-to-write-good-pr-titles) +1. be written from a user's perspective (what the user gets) +1. use present tense to describe the change ``` // Good examples: From 85473321a0ed89b6c8988bf0764914bc5b5e6364 Mon Sep 17 00:00:00 2001 From: Lucky Ivanius Date: Fri, 2 May 2025 18:16:38 +0700 Subject: [PATCH 3/6] docs: fix grammar and punctuation --- .github/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e85284e..0bef10f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -170,7 +170,7 @@ Thus, the names of the PRs must: 1. be oriented toward the end users 1. follow [Conventional Commits Guidelines](https://www.conventionalcommits.org) 1. be [clean and simple](https://pulsar.apache.org/contribute/develop-semantic-title/#how-to-write-good-pr-titles) -1. be written from a user's perspective (what the user gets) +1. be written from the user's perspective (what the user gets) 1. use present tense to describe the change ``` @@ -212,7 +212,7 @@ The key differences are: - "modify door handler" - describes code changes - None of these tell users what they can actually do -This makes it immediately clear that PR names should describe features from the user's perspective rather than the technical components used to implement them. +This makes it immediately clear that PR names should describe features from the user's perspective, rather than the technical components used to implement them. ## Requesting Review From a631cceac7d5f2de5895cc1a1d6efa1bf42d8362 Mon Sep 17 00:00:00 2001 From: Vadim Date: Tue, 3 Jun 2025 08:56:27 +0800 Subject: [PATCH 4/6] Update CONTRIBUTING.md Signed-off-by: Vadim --- .github/CONTRIBUTING.md | 86 +++++++++++++++++++---------------------- 1 file changed, 40 insertions(+), 46 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 0bef10f..2fc834c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -164,55 +164,49 @@ If there isn't an existing DESIGN.md file: ## Naming -We are using commits (PR names) to communicate the release log to all stakeholders, including non-technical ones. -Thus, the names of the PRs must: +We use PR titles to communicate changes to all stakeholders, including non-technical users. Follow these rules: -1. be oriented toward the end users -1. follow [Conventional Commits Guidelines](https://www.conventionalcommits.org) -1. be [clean and simple](https://pulsar.apache.org/contribute/develop-semantic-title/#how-to-write-good-pr-titles) -1. be written from the user's perspective (what the user gets) -1. use present tense to describe the change +1. **User-focused**: Describe what users gain, not technical implementation +2. **Follow [Conventional Commits](https://www.conventionalcommits.org)** +3. **Clear & simple** (present tense, action-oriented) -``` -// Good examples: - - feat(ui): play music - - fix(sdk): mute sound - - test(api): open door - -// Bad examples: - - create a player - - fix: add a file to mute sound - - feat: modified door function -``` +### Example Comparison + +| **Good Examples** ✅ | **Bad Examples** ❌ | **Why?** | +|-----------------------------|----------------------------------|---------| +| `feat(ui): play music` | "Create player" | Missing scope/type | +| `fix(sdk): mute sound` | "Fix: add file to mute sound" | Technical details | +| `test(api): open door` | "Feat: modified door function" | Vague, past tense | + +--- + +### Key Principles + +#### **What to Focus On** +A feature isn’t a button, toggle, or handler—it’s **what the user gains from it**. Ask: +- ❌ *"What am I building?"* → Leads to technical labels. +- ✅ *"What will users be able to do?"* → Leads to clear value. + +#### **Why It Matters** +- **Clarity**: Engineers, PMs, and stakeholders instantly understand the impact. +- **Consistency**: Aligns with product-facing language (release notes, docs). +- **User-Centricity**: Work is driven by user needs, not just code changes. + +#### **How to Apply It** +1. **Replace UI labels with actions**: + - 🚫 "Add dropdown for filters" → ✅ "Filter search results by category" +2. **Describe outcomes, not components**: + - 🚫 "Fix API error handling" → ✅ "Gracefully recover from connection errors" +3. **Use user action verbs**: + - *View, Play, Customize, Save*, etc. + + +### Before Submitting, Ask: +1. Does it use `type(scope): action` format? +2. Could a non-technical user understand the benefit? +3. Is it in the present tense? +4. Does it focus on user capability (not code)? -> [!IMPORTANT] -> When naming PRs, focus on describing the user capability (what they can do) rather than the technical implementation (how it's done): -> -> Compare these examples: -> - ❌ "quick custom subscribe button" - describes an object -> - ✅ "customize subscription preferences" - describes user capability -> -> Think of it this way: -> - A button isn't a feature; what it enables users to do is the feature -> - A toggle isn't a feature; the control it gives users is the feature -> - A handler isn't a feature; the functionality it provides is the feature -> -> Always ask yourself: "What will users be able to do?" instead of "What am I building?" - -The key differences are: - -1. Good examples focus on user capabilities: - - "enable music playback control" instead of "add play button" - - "prevent sound during mute state" instead of "add mute toggle" - - Each name describes what users can accomplish - -2. Bad examples focus on technical implementation: - - "subscribe button" - just names a UI element - - "add mute toggle" - describes a component - - "modify door handler" - describes code changes - - None of these tell users what they can actually do - -This makes it immediately clear that PR names should describe features from the user's perspective, rather than the technical components used to implement them. ## Requesting Review From 14e906faff1e8e29cf9e398739368b2d3ed32b64 Mon Sep 17 00:00:00 2001 From: Vadim Date: Tue, 3 Jun 2025 09:03:50 +0800 Subject: [PATCH 5/6] Update CONTRIBUTING.md Signed-off-by: Vadim --- .github/CONTRIBUTING.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 2fc834c..e90f1e2 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -164,7 +164,10 @@ If there isn't an existing DESIGN.md file: ## Naming -We use PR titles to communicate changes to all stakeholders, including non-technical users. Follow these rules: +> [!NOTE] +> We use PR titles to communicate changes to all stakeholders, including non-technical users. + +PR names must be: 1. **User-focused**: Describe what users gain, not technical implementation 2. **Follow [Conventional Commits](https://www.conventionalcommits.org)** @@ -174,9 +177,9 @@ We use PR titles to communicate changes to all stakeholders, including non-techn | **Good Examples** ✅ | **Bad Examples** ❌ | **Why?** | |-----------------------------|----------------------------------|---------| -| `feat(ui): play music` | "Create player" | Missing scope/type | -| `fix(sdk): mute sound` | "Fix: add file to mute sound" | Technical details | -| `test(api): open door` | "Feat: modified door function" | Vague, past tense | +| `feat(ui): play music` | `Create player` | Missing scope/type | +| `fix(sdk): mute sound` | `Fix: add file to mute sound` | Technical details | +| `test(api): open door` | `Feat: modified door function` | Vague, past tense | --- @@ -193,12 +196,9 @@ A feature isn’t a button, toggle, or handler—it’s **what the user gains fr - **User-Centricity**: Work is driven by user needs, not just code changes. #### **How to Apply It** -1. **Replace UI labels with actions**: - - 🚫 "Add dropdown for filters" → ✅ "Filter search results by category" -2. **Describe outcomes, not components**: - - 🚫 "Fix API error handling" → ✅ "Gracefully recover from connection errors" -3. **Use user action verbs**: - - *View, Play, Customize, Save*, etc. +1. **Replace UI labels with actions**: 🚫 "Add dropdown for filters" → ✅ "Filter search results by category" +2. **Describe outcomes, not components**: 🚫 "Fix API error handling" → ✅ "Gracefully recover from connection errors" +3. **Use user action verbs**: *View, Play, Customize, Save*, etc. ### Before Submitting, Ask: From 4b321dfa0618dbbcaa2b89f8a5c77f9afcf6ee52 Mon Sep 17 00:00:00 2001 From: Vadim Date: Tue, 3 Jun 2025 09:05:20 +0800 Subject: [PATCH 6/6] Update CONTRIBUTING.md Signed-off-by: Vadim --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e90f1e2..b2a76bf 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -201,7 +201,7 @@ A feature isn’t a button, toggle, or handler—it’s **what the user gains fr 3. **Use user action verbs**: *View, Play, Customize, Save*, etc. -### Before Submitting, Ask: +### Before Submitting, Ask 1. Does it use `type(scope): action` format? 2. Could a non-technical user understand the benefit? 3. Is it in the present tense?