Contributing Guide

This guide covers the development workflow, coding standards, and contribution guidelines for the Flow Reference Wallet monorepo.

📋 Table of Contents

Development Setup
Commit Message Guidelines
Code Quality Standards
Pull Request Process
Architecture Guidelines

🚀 Development Setup

Prerequisites

Node.js: >= 20.0.0
pnpm: >= 9.0.0 (automatically managed via packageManager field)
Git: Latest version with proper SSH/HTTPS setup

Getting Started

Clone the repository

git clone https://github.com/onflow/FRW-monorepo.git
cd FRW

Install dependencies
```
pnpm install
```
Build all packages
```
pnpm build:packages
```

Run development environment

# For React Native development
pnpm dev:rn:full

# For Extension development
pnpm dev:extension

# For package development only
pnpm dev:packages

🌿 Branch Naming & Issue Tracking

All non-maintenance branches must include an issue number for automatic tracking and commit linking.

Recommended Patterns

Main branches (no issue number required): main, master, dev, develop
Maintenance branches (recommended GitFlow style):
- hotfix/<desc> or hotfix/<issue>-<desc> (e.g., hotfix/249-critical-bug)
- release/<version> or release/<issue>-<version> (e.g., release/1.2.3)
Feature/fix branches (must contain issue number):
- 123-feature-title (GitHub default when branching from an issue)
- feature-123
- dev/123-feature-title
- feature/abc-123

Note: We recommend hotfix/* and release/* (with slashes). Hyphen forms like hotfix-... and release-... are currently permitted for compatibility but may be restricted later.

Invalid Patterns (blocked by hooks)

Missing issue number on feature/fix branches: feature/add-authentication, random-branch
Obsolete maintenance naming: update-* (no longer allowed)
Generic names without numbers: experiment-x, bugfix/something

Quick Start

Use GitHub's default format when creating branches from issues:

# ✅ Correct (contains issue number)
123-add-user-authentication
feature-789-wallet-integration
dev/285-improve-performance

# ❌ Incorrect (no issue number)
add-user-authentication
my-cool-feature

Automated Workflow

Create Issue → GitHub generates branch name 123-feature-name
Create Branch → git checkout -b 123-feature-name
Normal Commits → git commit -m "feat: add authentication"
Auto-Enhancement → Husky adds Closes #123 automatically (from branch name)
Result → Full traceability in release notes

📝 Commit Message Guidelines

We use Conventional Commits specification with automatic issue number injection.

Format

<type>[optional scope]: <description>

[Automatically added by Husky]
Closes #123

Note: Issue numbers are automatically extracted from branch names and added to commit messages!

Commit Types

Core Types (Required)

Type	Purpose	Example
`feat`	New features	`feat: add user authentication system`
`fix`	Bug fixes	`fix: resolve login timeout issue`

Common Types

Type	Purpose	Example
`docs`	Documentation changes	`docs: update API reference guide`
`style`	Code formatting (no logic changes)	`style: fix ESLint warnings in utils`
`refactor`	Code refactoring	`refactor: extract validation logic to service`
`perf`	Performance improvements	`perf: optimize query response time`
`test`	Test additions/modifications	`test: add unit tests for auth service`
`build`	Build system changes	`build: update webpack configuration`
`ci`	CI/CD configuration changes	`ci: add automated deployment workflow`
`chore`	Maintenance tasks	`chore: update npm dependencies`

Extended Types

Type	Purpose	Example
`security`	Security fixes	`security: patch XSS vulnerability in forms`
`deps`	Dependency updates	`deps: bump react from 18.2.0 to 19.0.0`
`config`	Configuration changes	`config: update ESLint rules for TypeScript`
`hotfix`	Critical production fixes	`hotfix: resolve payment gateway timeout`
`cleanup`	Code cleanup	`cleanup: remove unused imports and files`

Scope Examples

Scopes help identify which part of the codebase is affected:

feat(auth): add OAuth2 integration
fix(ui): resolve button alignment in modal
docs(api): add endpoint documentation
test(stores): add unit tests for wallet store
chore(deps): update Flow SDK to latest version

Breaking Changes

Use ! after the type or BREAKING CHANGE: in the footer:

# Method 1: Using exclamation mark
feat!: remove deprecated login API

# Method 2: Using footer
feat: update authentication system

BREAKING CHANGE: The /api/v1/login endpoint has been removed.
Use /api/v2/auth/login instead.

Examples

Simple Commits

feat: add dark mode toggle to settings
fix: resolve memory leak in token refresh
docs: add React Native development guide
test: add integration tests for send flow
chore: update TypeScript to version 5.7

Scoped Commits

feat(wallet): implement multi-account support
fix(nft): resolve image loading timeout
style(components): apply consistent button styling
perf(api): optimize batch token price fetching

Multi-line Commits

feat: implement comprehensive user dashboard

- Add user profile management interface
- Create activity timeline with transaction history
- Implement settings panel with preferences
- Integrate real-time notification system
- Add responsive design for mobile devices

Closes #123
Co-authored-by: John Doe <[email protected]>

❌ Common Mistakes

# ❌ Wrong - Missing type
"Update user interface"

# ❌ Wrong - Invalid type
"updated: fix login bug"

# ❌ Wrong - Missing colon and space
"fix:login timeout"

# ❌ Wrong - Uppercase first letter
"fix: Fix login timeout"

# ❌ Wrong - Ending with period
"fix: resolve login timeout."

# ✅ Correct
"fix: resolve login timeout issue"

🔧 Fixing Failed Commits

If commitlint fails, you can fix your commit message:

# Fix the most recent commit message
git commit --amend -m "fix: resolve login timeout issue"

# For older commits, use interactive rebase
git rebase -i HEAD~3  # Edit last 3 commits

🧹 Code Quality Standards

Automated Quality Checks

Our monorepo includes automated code quality enforcement:

ESLint: Linting for TypeScript/JavaScript
Prettier: Code formatting
Husky: Git hooks for pre-commit checks
lint-staged: Runs checks only on staged files

Pre-commit Hooks

Every commit automatically runs:

ESLint with auto-fix on staged .ts, .tsx, .js, .jsx files
Prettier formatting on staged files
commitlint validation on commit message

Manual Quality Checks

# Run ESLint on entire codebase
pnpm lint

# Fix ESLint issues automatically
pnpm lint:fix

# Check Prettier formatting
pnpm format:check

# Format all files with Prettier
pnpm format

# Run TypeScript type checking
pnpm typecheck

# Run all tests
pnpm test

Code Style Guidelines

Use TypeScript for all new code
Prefer explicit return types for functions in packages
Use consistent naming: camelCase for variables/functions, PascalCase for components
Comment complex logic but prefer self-documenting code
Keep functions small and focused on single responsibility
Use meaningful variable names that describe the data

🔄 Pull Request Process

Before Creating a PR

Create a feature branch

git checkout -b feat/user-authentication
git checkout -b fix/login-timeout
git checkout -b docs/contributing-guide

Make your changes following the coding standards

Test your changes

pnpm build:packages  # Ensure packages build
pnpm lint           # Check for linting issues
pnpm typecheck      # Verify TypeScript types
pnpm test           # Run tests

Commit with conventional format

git add .
git commit -m "feat: add user authentication system"

Creating the PR

Push your branch

git push origin feat/user-authentication

Create PR with clear title and description:
- Title should follow conventional commits format
- Description should explain what changes were made and why
- Link relevant issues with Closes #123

PR Requirements

✅ Required Checks

All CI checks must pass
Code review approval from at least one maintainer
No merge conflicts
Conventional commit format

✅ Best Practices

Keep PRs focused and reasonably sized
Update documentation if needed
Add tests for new features
Ensure backward compatibility

🏗️ Architecture Guidelines

Monorepo Structure

FRW/
├── packages/          # Shared packages
│   ├── api/          # API client and types
│   ├── cadence/      # Flow blockchain interactions
│   ├── context/      # Dependency injection
│   ├── services/     # Business logic services
│   ├── stores/       # State management (Zustand)
│   ├── types/        # Shared TypeScript types
│   ├── utils/        # Utility functions
│   └── workflow/     # Complex business workflows
├── apps/
│   ├── react-native/ # Mobile application
│   └── extension/    # Browser extension
└── docs/             # Documentation

Development Principles

MVVM Architecture: Types → API/Cadence → Services/Workflow → Stores → UI
Dependency Injection: Use ServiceContext for loose coupling
Package Independence: Packages should not depend on apps
Shared State: Use Zustand stores for cross-component state
Type Safety: Prefer TypeScript strict mode everywhere

Import Guidelines

// ✅ External packages first
import React from 'react';
import { z } from 'zod';

// ✅ Internal packages
import { ApiClient } from '@onflow/frw-api';
import { WalletService } from '@onflow/frw-services';

// ✅ Relative imports last
import { Button } from '../components/Button';
import { useWallet } from './hooks/useWallet';

🤝 Getting Help

Documentation: Check /docs directory for detailed guides
Issues: Create GitHub issues for bugs or feature requests
Discussions: Use GitHub Discussions for questions
Code Review: Don't hesitate to ask for feedback in PRs

📚 Additional Resources

Happy contributing! 🚀

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History