diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f586a76..b2a76bf 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -164,24 +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: +> [!NOTE] +> We use PR titles to communicate changes to all stakeholders, including non-technical users. -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) +PR names must be: + +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) + +### 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)? -``` -// 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 -``` ## Requesting Review