Skip to content

Commit 547957d

Browse files
committed
docs(contributing): simplify language throughout
1 parent a8fe878 commit 547957d

1 file changed

Lines changed: 18 additions & 40 deletions

File tree

docs/CONTRIBUTING.md

Lines changed: 18 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,5 @@
11
# Contributing Guidelines
22

3-
Thank you for your interest in contributing to our project! Your accepted
4-
contributions will be reflected in our repositories and related websites.
5-
63
Please read our [Code of Conduct](./CODE_OF_CONDUCT.md) to keep our community
74
approachable and respectful.
85

@@ -30,7 +27,7 @@ approachable and respectful.
3027
There are three core contribution pillars:
3128

3229
1. **Goal** – a business aim
33-
1. **Problem**an issue that is on our way to achieving the Goal
30+
1. **Problem**a barrier to achieving the Goal
3431
1. **Solution** – the actual deliverable which resolves the problem
3532

3633
### Goal
@@ -57,9 +54,8 @@ As soon as you get involved, you must:
5754
5855
### Problem
5956

60-
Once a Goal is clear, you must identify what prevents its achievement. Anything
61-
that acts as a barrier is considered a "Problem." Ask yourself: "Why is this
62-
Goal not achieved, and what specifically is the problem?"
57+
Once a Goal is clear, identify what prevents its achievement. Anything that
58+
acts as a barrier is a Problem.
6359

6460
> [!NOTE]
6561
> Report each Problem as a [GitHub Issue](https://docs.github.com/en/issues)
@@ -92,7 +88,6 @@ Describe the recommended approach or workaround.
9288

9389
### Solution
9490

95-
Different problems may require different sets of skills.
9691
Whether it's code, design, or marketing material, we expect a lean and clean
9792
solution from the contributor.
9893

@@ -163,7 +158,7 @@ use Goal issue comments for scope discussions — they belong in the Spec.
163158

164159
### Discussion channels
165160

166-
Direct discussions to the appropriate channel at all times:
161+
Direct discussions to the appropriate channel:
167162

168163
- **Spec file** — clarifications about Goal scope or business context; propose
169164
changes via PR or review comments on an open Spec PR
@@ -188,9 +183,8 @@ issue so the dependency is visible.
188183

189184
### Referencing issues and PRs
190185

191-
When referencing issues or pull requests, use a list item format to enable
192-
automatic title rendering and improve readability. This ensures that GitHub
193-
automatically expands the reference to show the issue/PR title.
186+
When referencing issues or pull requests, use a list item format — GitHub
187+
automatically expands it to show the title.
194188

195189
**Correct** — use a list item:
196190

@@ -212,11 +206,8 @@ Check this out: <issue_or_pr_url> Related: <issue_or_pr_url> See
212206

213207
## PR Requirements
214208

215-
All PRs, whether for source code, design, or copy changes, must comply with the
216-
following requirements.
217-
218209
> [!WARNING]
219-
> PRs that do not correspond to the following criteria will be rejected.
210+
> PRs that do not meet the following requirements will be rejected.
220211
221212
Before marking your PR as ready for review, confirm:
222213

@@ -234,10 +225,8 @@ Before marking your PR as ready for review, confirm:
234225

235226
### Commit Signature Verification
236227

237-
For the security and integrity of our project, we require all contributors to
238-
sign their commits.
239-
For detailed instructions on why and how to sign your commits refer to
240-
[GitHub's documentation on commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
228+
All commits must be signed. See [GitHub's documentation on commit signature
229+
verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
241230

242231
> [!NOTE]
243232
> We recommend signing commits using an
@@ -257,9 +246,8 @@ You must be able to complete your PR within 3–4 hours.
257246
If the solution requires more time, then decompose it into smaller independent
258247
PRs. In case your smaller PRs can't be used on production, use feature flags.
259248

260-
We usually reject and close PRs which do not have activity for the last 24
261-
hours, unless there is a clear comment explaining the reason why that PR is
262-
stalled.
249+
PRs with no activity for 24 hours are closed unless a comment explains the
250+
delay.
263251

264252
When introducing functional changes, cross-check the README and update it in the
265253
same PR. If your change affects anything documented there — setup steps,
@@ -291,15 +279,9 @@ PR names must be:
291279
| `fix(sdk): mute sound` | `Fix: add file to mute sound` | Technical details |
292280
| `test(api): open door` | `Feat: modified door function` | Vague, past tense |
293281

294-
A feature isn't a button, toggle, or handler — it's
295-
**what the user gains from it**. Ask _"What will users be able to do?"_ not
296-
_"What am I building?"_
297-
298-
1. **Replace UI labels with actions**: Wrong: "Add dropdown for filters" →
299-
Correct: "Filter search results by category"
300-
1. **Describe outcomes, not components**: Wrong: "Fix API error handling" →
301-
Correct: "Gracefully recover from connection errors"
302-
1. **Use user action verbs**: _View, Play, Customize, Save_, etc.
282+
A feature isn't a button, toggle, or handler — it's what the user gains from
283+
it. Ask _"What will users be able to do?"_ not _"What am I building?"_ Use
284+
action verbs: _View, Play, Customize, Save_.
303285

304286
> [!WARNING]
305287
> This rule applies to **all PR types**, including `docs`. Do not use verbs that
@@ -392,17 +374,13 @@ the PR.
392374

393375
#### Scout Approach
394376

395-
If you ever have free time, be proactive and apply the scout approach: own the
396-
job, look for PRs that still need reviewers, and offer timely feedback so work
397-
keeps moving.
377+
When not actively working on a PR, look for PRs that need reviewers and offer
378+
timely feedback to keep work moving.
398379

399380
#### Code Quality
400381

401-
Aim for solutions that work correctly 99.9% of the time. Be independent and
402-
thorough in your QA — reviewers are not QA team members but are there for a
403-
final safety check. We expect contributors to deliver bug-free software,
404-
understanding that perfection is an ideal. Stand firm in your solutions and
405-
avoid unnecessary revisions based on subjective feedback.
382+
Deliver bug-free software. Push back on subjective feedback — reviewers are a
383+
final safety check, not a QA team.
406384

407385
---
408386

0 commit comments

Comments
 (0)