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-
63Please read our [ Code of Conduct] ( ./CODE_OF_CONDUCT.md ) to keep our community
74approachable and respectful.
85
@@ -30,7 +27,7 @@ approachable and respectful.
3027There are three core contribution pillars:
3128
32291 . ** 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
34311 . ** 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.
9691Whether it's code, design, or marketing material, we expect a lean and clean
9792solution 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
221212Before 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.
257246If the solution requires more time, then decompose it into smaller independent
258247PRs. 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
264252When introducing functional changes, cross-check the README and update it in the
265253same 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