Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
399 lines (294 loc) · 14.6 KB

CONTRIBUTING.md

File metadata and controls

399 lines (294 loc) · 14.6 KB

Contributing Guidelines

Thank you for your interest in contributing to our project! Your accepted contributions will be reflected in our repositories and related websites.

Please read our Code of Conduct to keep our community approachable and respectful.

Tip

You can use Wizard GitHub App and Wizard Browser Extension to simplify some of the workflows described in these Guidelines.

Table of Contents

Getting started

There are three core contribution pillars:

  1. Goal – a business aim
  2. Problem – an issue that is on our way to achieving the Goal
  3. Solution – the actual deliverable which resolves the problem

Goal

To find a Goal to work on, browse GitHub Issues in the relevant repository and filter for issues with the Goal: prefix. Prioritize issues based on their impact and urgency. If you are unsure which Goal to choose, please consult your lead.

As soon as you get involved, you must:

  1. assign yourself to the Goal issue.
  2. review the Spec linked from the Goal issue and assess outstanding Problems,
  3. provide an estimated time of achieving (ETA) the Goal.

Note

Goals follow the naming pattern: Goal: [statement] and must link to a Spec with an ETA.

Problem

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

Note

Report each Problem as a GitHub Issue using the naming pattern: Problem: [statement]. Keep it short (under 65 characters). Add it as a sub-issue of the Goal and include the Goal issue link in the description.

The statement must be a job story — describe what a specific user cannot do or what is broken for them. Ask: "What can [user] not do because of this problem?"

Good ✅ Bad ❌ Why?
operators can't view their account balance operators don't have their account balance Describes inability, not state
users can't submit a form without refreshing form submission issue Vague, no actor or action
admins can't export reports as CSV CSV export missing No subject, not a job story

Every Problem issue body must include both a # Problem and a # Solution section, describing the recommended approach or workaround before work begins.

# Problem

Describe what the user cannot do and why it matters.

## Solution

Describe the recommended approach or workaround.

Solution

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

Note

Solution is presented in GitHub as a Pull Request (PR) in compliance with PR Requirements.

For reimbursable work-related costs, see Expenses.

Specs

A Spec describes the intended behavior for a Goal — not what currently exists, but what the Goal aims to deliver. The canonical Spec is a markdown file in docs/specs/. When external stakeholders need to collaborate, a Google Document may supplement it, but the markdown file is what the development team builds against.

A Goal must not be opened without a linked Spec.

Lifecycle

A Spec file shrinks as the Goal is implemented. Each PR that delivers behavior described in the Spec must move the corresponding sections from docs/specs/<feature>.md into the appropriate file in docs/. When the Spec file has no remaining sections, delete it — the Goal is fully documented.

docs/specs/<feature>.md   ← only unimplemented sections
docs/<feature>.md         ← only what is currently shipped

Never add unimplemented behavior to docs/. Never leave implemented behavior in docs/specs/.

Format

_Goal: <link to Goal issue>_

## Overview

What this Goal enables for users.

## [Section]

Describe what users can do, not how the system works internally.

Sections are defined by the author. Keep them user-focused and scoped to observable behavior. Include a ## Design section using the markup described in Design PRs when the Goal has a design component.

Discussing a Spec

If the Spec PR is not yet merged, propose changes via review comments on that PR. If the Spec is already merged, open a new PR against the spec file. Do not use Goal issue comments for scope discussions — they belong in the Spec.

Communication Guidelines

Discussion channels

Direct discussions to the appropriate channel at all times:

  • Spec file — clarifications about Goal scope or business context; propose changes via PR or review comments on an open Spec PR
  • Problem issues — tracking obstacles that prevent achieving the Goal
  • Goal issues — linking Specs, tracking Problems, and monitoring progress only

Important

Do not post Problem status updates, PR notifications, or progress updates in Goal issues. The Goal → Problem → PR chain makes these redundant and adds noise.

If you identify a potential new problem but are unsure whether it is planned:

  1. Check if there is an existing Problem issue related to your concern.
  2. If not, open a PR against the Spec file, or leave a review comment if the Spec PR is not yet merged.
  3. If necessary, create a new Problem issue and discuss it there.

If someone's action is required to unblock progress, assign them to the Goal issue so the dependency is visible.

Referencing issues and PRs

When referencing issues or pull requests, use a list item format to enable automatic title rendering and improve readability. This ensures that GitHub automatically expands the reference to show the issue/PR title.

Correct — use a list item:

See these related items:

- <issue_or_pr_url>
- <another_issue_or_pr_url>
- #4
- #12

Incorrect — avoid inline pasting:

Check this out: <issue_or_pr_url> Related: <issue_or_pr_url> See
<issue_or_pr_url> for details

PR Requirements

All PRs, whether for source code, design, or copy changes, must comply with the following requirements.

Warning

PRs that do not correspond to the following criteria will be rejected.

Before marking your PR as ready for review, confirm:

  • Commits are signed
  • PR scope fits within 3–4 hours of work
  • All CI checks pass
  • PR is linked to a Problem issue
  • At least one reviewer is assigned
  • Time is reported
  • PR title follows type(scope): action naming convention
  • Preview link is included (if applicable)
  • README is updated to reflect any functional changes
  • Spec sections moved to docs/ for any behavior this PR delivers (if applicable)

Commit Signature Verification

For the security and integrity of our project, we require all contributors to sign their commits.
For detailed instructions on why and how to sign your commits refer to GitHub's documentation on commit signature verification.

Note

We recommend signing commits using an SSH key. Ensure your Git version supports SSH signature verification (Git 2.34 or later).

Scoping

Tip

Here's a good resource on software design philosophy.

When planning the scope of work, make sure you keep PRs small. You must be able to complete your PR within 3–4 hours.
If the solution requires more time, then decompose it into smaller independent PRs. In case your smaller PRs can't be used on production, use feature flags.

We usually reject and close PRs which do not have activity for the last 24 hours, unless there is a clear comment explaining the reason why that PR is stalled.

When introducing functional changes, cross-check the README and update it in the same PR. If your change affects anything documented there — setup steps, environment requirements, file references — the README must stay in sync.

When adding new documentation files, ensure they are reachable via interlinking from the root entry point. Do not create orphaned files.

Do not duplicate content across files. Each piece of information — procedures, templates, configuration steps — must live in exactly one place. Reference it from other docs rather than copying it.

Naming

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
  3. Clear & simple (present tense, action-oriented)
  4. Under 65 characters
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

A feature isn't a button, toggle, or handler — it's what the user gains from it. Ask "What will users be able to do?" not "What am I building?"

  1. Replace UI labels with actions: Wrong: "Add dropdown for filters" → Correct: "Filter search results by category"
  2. Describe outcomes, not components: Wrong: "Fix API error handling" → Correct: "Gracefully recover from connection errors"
  3. Use user action verbs: View, Play, Customize, Save, etc.

Warning

This rule applies to all PR types, including docs. Do not use verbs that describe what you did ("document", "update", "add") — use verbs that describe what users can now do.

Good ✅ Bad ❌
docs(typefully): log in with shared account docs(typefully): document shared account
docs(api): authenticate with OAuth docs(api): add OAuth section to README

Design PRs

Design PRs use docs(ui) as the type and scope. e.g.: docs(ui): design table component

Add a ## Design section to the relevant Spec file. Structure it with the following markup:

## Design
- [/page](https://figma.com/your-design-file-url)
  - ./page/{params}
    - (group)
      - [[state]](https://figma.com/your-design-file-url)

Key:

  • /... — a page
  • {...} — a dynamic URL parameter
  • (...) — a grouping of related features or components
  • [...] — a specific state (e.g. popup or modal)
  • Indentation represents nesting hierarchy

Example:

## Design
- [/lending](https://figma.com/your-design-file-url)
  - ./vaults/{poolAddr}
    - (Auction)
      - [[Withdraw Popup]](https://figma.com/your-design-file-url)
      - [[Bid Popup]](https://figma.com/your-design-file-url)

PR Lifecycle

Follow these steps in order from start to submission:

  1. Open a draft PR right away when you start working on a Problem.
  2. Link the PR to the corresponding Problem issue using a closing keyword.
  3. Assign yourself so it is clear who is working on it.
  4. Report your time spent across all stages: planning (40%), implementation, and QA (20–30%). Open the PR early so time tracking starts from the beginning, including investigation.
  5. Assign at least one reviewer (team or individual).
  6. Include a preview link — if your changes are visually verifiable (UI, design, or any deployable artifact), add a link to the deployed preview or prototype in the PR description.
  7. Mark as ready for review only once all steps above are complete.
  8. Resolve all CI checks — CI runs after marking ready; do not request approval until all checks pass.

Warning

Do not merge without an approved review and passing CI checks.

Review Process

Giving a Review

If a PR is not ready to merge, you must use Request Changes (reject). Do not leave a plain comment when rejection is warranted — comments do not block merging, are not recorded as rejections, and prevent the author from re-requesting a review.

Use Request Changes (reject) for objective problems:

  • PR doesn't solve the stated problem.
  • A bug is introduced.
  • Code style is inconsistent.
  • Required guidelines are violated.

Use Comment for optional improvements or suggestions that should not block the PR.

Scout Approach

If you ever have free time, be proactive and apply the scout approach: own the job, look for PRs that still need reviewers, and offer timely feedback so work keeps moving.

Code Quality

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