Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
374 lines (276 loc) · 13.8 KB

CONTRIBUTING.md

File metadata and controls

374 lines (276 loc) · 13.8 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

Note

In this guide you will get an overview of the contribution workflow: from finding a Goal, identifying a Problem, and the process of delivering your solutions.

Goal

Understanding the Goal and its business context is crucial for successful contribution.

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. Pick one that matches your skills, then proceed with the steps below.

As soon as you get involved, you must:

  1. assign yourself to the Goal issue.
  2. analyze specifications (the Specs),
  3. assess progress and outstanding Problems and
  4. provide an estimated time of achieving (ETA) the Goal.

Each Goal description must include Specs (a Google Document with commenting permissions) and an ETA.

Note

A Goal is represented as a GitHub issue in the relevant repository and has the following naming pattern: Goal: [statement].
Goals are created and managed by Partner level contributors.

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 the name short (under 65 characters) and crystal clear.

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

Ensure each Problem issue is properly interlinked with its parent Goal issue:

  • Add the Problem as a sub-issue of the Goal using GitHub's sub-issue feature.
  • Add the Goal issue link to the Problem description.

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

The third pillar of successful contribution is the 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.

Communication Guidelines

Discussion channels

Direct discussions to the appropriate channel at all times:

  • Spec document — clarifications about Goal scope or business context
  • 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, ask for clarification in the Spec document.
  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

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

Before Submitting, Ask

  1. Does it use type(scope [Optional]): 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)?
  5. Is it under 65 characters?

Design PRs

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

Initiate a PR with a note in the DESIGN.md file detailing the addressed design aspects. Structure the design file with the following markup:

## Feature
- [/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:

## Credit Vaults
- [/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)

If there isn't an existing DESIGN.md file, create one and link it from README.md.

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. Resolve all CI checks — PRs with failing checks will be rejected.
  5. 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.
  6. Assign at least one reviewer (team or individual).
  7. 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.
  8. Mark as ready for review only once all steps above are complete.

Warning

Do not merge without an approved review.

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.