Skip to content

Latest commit

 

History

History
155 lines (107 loc) · 7.28 KB

CONTRIBUTING.md

File metadata and controls

155 lines (107 loc) · 7.28 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 respectable.

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.

As soon as you get involved, you must:

  1. analyze specifications (the Specs),
  2. assess progress and outstanding Problems and
  3. 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 the Goal is clear, you must identify what stops you from achieving it. Anything that is stopping you - is a “Problem”. A typical question to ask is: "Why is this Goal not achieved and what is the Problem?".

Sometimes, a Goal already has a few identified problems, but not always.

Note

Once a Problem is identified, we report it as a GitHub Issue with the following naming pattern: Problem: [statement].
We’re counting on our contributors to identify problems. Keep a Problem name short (under 65 chars) and crystal clear.

Make sure each Problem issue is interlinked with it's Goal issue:

  • add a Problem issue link into the Goal description
  • add a Goal issue link to the Problem description

It's essential to maintain clear links between Goals and related Problem issues. This helps everyone stay informed and team members can easily track progress and understand the context.

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 Pull Requests (PR) in compliance with PR Requirements.

PR Requirements

All PRs, whether for source code, design, or copy changes, must comply with our PR Requirements.

Warning

PRs that do not correspond to the following criteria are usually rejected.

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

Note

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.

Drafting

When start working on a Problem, you must open a draft PR right away. Do not mark PR as "ready to review" unless you are confident it is ready.

When creating a PR, you must link it to the corresponding Problem (issue).

Design PRs

Initiate a PR with a note in the DESIGN.md file detailing the addressed design aspects. Design PRs use docs(ui) as the "type" and "scope" of its name. i.e.: docs(ui): design table component

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:

  • /... - Represents a page.

  • {...} - Represents a dynamic parameter within a URL.

  • (...) - Used for grouping related features or components.

  • [...] - Indicates a specific state of the page or component, such as a popup or modal state.

  • Indentation in the list represents the tree structure or hierarchy, showing how components or features are nested or related.

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:

  1. Create a new file named DESIGN.md.
  2. Link it from README.md.

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:

  1. be oriented toward the end users
  2. follow Conventional Commits Guidelines
  3. be clean and simple
// 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

Once your PR is ready, assign reviewers and mark it as "ready to review." But before that, report the time you have spent on it.

Note

When contributing, it's essential to report time accurately, including all stages of development (planning, implementation, QA). We encourage opening a PR at the start of your work, even during the planning or investigation phase. Programming and designing isn't just about writing code or creating designs; it also involves planning (40%) and QA (20-30%).

Code Quality and Reviews

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.