Getting Started

​

Welcome Contributors!

​

Prerequisites

​

Required Knowledge

• JavaScript/TypeScript: Strong understanding required
• React & React Native: Experience building React applications
• Git: Familiarity with branching, commits, and pull requests
• Command Line: Comfortable using terminal/command prompt

​

Recommended Reading

1. CLAUDE.md: Complete repository overview
2. README.md: Development setup and testing
3. CONTRIBUTING.md: Contribution process and guidelines

​

Environment Setup

​

Quick Start

# 1. Install nvm (if not installed)
brew install nvm

# 2. Install Node.js and npm
nvm install

# 3. Install watchman
brew install watchman

# 4. Clone the repository
git clone https://github.com/Expensify/App.git
cd App

# 5. Install dependencies
npm install

# 6. Run the app
npm run web     # For web development
npm run ios     # For iOS (Mac only)
npm run android # For Android

​

Finding Issues to Work On

​

For External Contributors

1. Browse GitHub Issues: Look for issues with the Help Wanted label
2. Check Upwork: View available jobs on Upwork
3. Follow @ExpensifyOSS: Get notified of new jobs on Twitter

​

Before Proposing

1. Check for existing proposals: Read other proposals to ensure yours is different
2. Reproduce the issue: Verify you can reproduce the problem
3. Test on all platforms: iOS, Android, Web, mWeb, macOS

​

Creating Test Accounts

​

Important Guidelines

1. Use + in email addresses: e.g., [email protected]
   • Marks accounts as test accounts
   • Prevents assignment of Expensify Guides
2. Do not chat with Concierge: This diverts to customer support
3. Do not interact with onboarding teams: Let them know you’re a contributor
4. Do not post in public rooms: Use test rooms or this staging room

​

Generating Multiple Test Accounts

• [email protected]
• [email protected]
• [email protected]

​

Making Your First Contribution

​

Step 1: Reproduce the Issue

# Ensure you're on the latest main branch
git checkout main
git pull origin main

# Start the app
npm run web

​

Step 2: Create a Proposal

## Proposal

### Please re-state the problem that we are trying to solve in this issue
[Explain the problem in your own words]

### What is the root cause of that problem?
[Identify the root cause with file paths and line numbers]

### What changes do you think we should make in order to solve the problem?
[Detailed solution with code examples]

### What alternative solutions did you explore? (Optional)
[Other approaches you considered]

​

Proposal Guidelines

• Be specific: Include file paths and line numbers
• Be different: Don’t duplicate existing proposals
• Be thorough: Explain root cause, not just symptoms
• One proposal only: Don’t submit multiple proposals for same issue

​

Step 3: Wait for Selection

1. If selected, you’ll be hired on Upwork
2. The GitHub issue will be assigned to you
3. You can then begin coding

​

Step 4: Create a Branch

# Create a new branch from main
git checkout main
git pull origin main
git checkout -b fix/issue-description

# Example:
git checkout -b fix/chat-not-scrolling

​

Step 5: Make Your Changes

# Make code changes
# Test thoroughly on all platforms

# Format code with Prettier (REQUIRED)
npm run prettier

# Run linter
npm run lint

# Run type check
npm run typecheck-tsgo

​

Step 6: Commit Changes

# Stage changes
git add .

# Commit with a clear message
git commit -m "Fix: Prevent chat from scrolling on new message"

# Push to your fork
git push origin fix/chat-not-scrolling

​

Step 7: Create Pull Request

1. Go to GitHub and create a pull request from your branch
2. Fill out every section of the PR template
3. Link the issue: Fixes https://github.com/Expensify/App/issues/12345
4. Provide test steps for each platform
5. Include screenshots for each platform

​

Step 8: Code Review

• A Contributor+ (C+) team member
• An Expensify engineer

• Respond to feedback promptly
• Make requested changes
• Post “Updated” comment when ready for re-review
• Provide daily updates on weekdays
• Never force push after review starts

​

Step 9: Deployment & Payment

1. Merged: PR is merged to main
2. Deployed to Staging: Tested on staging environment
3. Deployed to Production: Released to all users
4. Regression Period: 7 days after production deploy
5. Payment: Issued 7+ days after production deploy (if no regressions)

​

Signing Commits

​

Setup GPG Signing

# 1. Generate GPG key
gpg --full-generate-key
# Select RSA, 4096 bits, no expiration
# Use your GitHub email

# 2. Get your GPG key ID
gpg --list-secret-keys --keyid-format LONG
# Copy the key ID after "sec   rsa4096/"

# 3. Export public key
gpg --armor --export YOUR_KEY_ID
# Copy the output

# 4. Add to GitHub
# Go to GitHub Settings > SSH and GPG keys
# Click "New GPG key" and paste

# 5. Configure git
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true
git config --global gpg.program gpg

​

Working on Beta Features

// Override in your local environment
// src/libs/Permissions.ts
export function canUseAllBetas(): boolean {
  return true; // Change from checking beta list
}

​

Communication Channels

​

Slack: #expensify-open-source

1. Fill out this form
2. Include your email and Upwork profile
3. Wait for approval

​

GitHub Issues

​

Email

• Security vulnerabilities: [email protected] (subject: “Vulnerability Report”)
• General inquiries: [email protected]

​

Payment Information

​

Getting Paid

1. Create Upwork account: Ensure profile is fully verified
2. Add profile to GitHub: Link in your GitHub bio
3. Apply on Upwork: After proposal is selected on GitHub
4. Payment timeline: 7+ days after production deployment

​

Payment via Expensify

​

Common Mistakes

​

1. Not Reading Documentation

​

2. Proposing Too Early

​

3. Not Testing All Platforms

​

4. Skipping Prettier

​

5. Not Signing Commits

​

6. Force Pushing During Review

​

Tips for Success

​

1. Start Small

​

2. Read Existing Code

​

3. Ask Questions Early

​

4. Provide Daily Updates

​

5. Be Patient

​

Next Steps

​

Additional Resources

• CONTRIBUTING.md
• Code of Conduct
• Contributor License Agreement
• Proposal Template
• How to Become a Contributor+