Contributing Guide

Thank you for contributing to The Mempool Open Source Project! This guide will help you understand the contribution process and requirements.

The Mempool Open Source Project is managed by Mempool Holdings S.A. de C.V. in El Salvador.

Before You Start

All contributors must agree to the Contributor License Agreement (CLA) before their contributions can be merged.

First-time contributors must create a CLA agreement file before submitting pull requests.

Quick Start

Fork and Clone

Fork the repository and clone it locally:

git clone https://github.com/YOUR_USERNAME/mempool.git
cd mempool

Create a Branch

Create a feature branch for your changes:

git checkout -b feature/your-feature-name

Make Your Changes

Make your changes following the code standards below.

Sign Your Commits

All commits must be GPG-signed.

Enable GPG signing:

git config commit.gpgsign true

Commit your changes:

git add .
git commit -m "feat: add new feature"

Run Tests

Ensure all tests pass:

# Backend tests
cd backend
npm test

# Frontend tests
cd ../frontend
npm test
npm run cypress:run

Push and Create PR

Push your branch and create a pull request:

git push origin feature/your-feature-name

Go to GitHub and open a pull request against the master branch.

Contributor License Agreement

First-Time Contributors

When submitting your first pull request, you must create a CLA agreement file:

Create Your CLA File

Create a file named /contributors/{github_username}.txt in the repository.

Add Agreement Statement

In this file, indicate your agreement to the CLA terms:

I, [Your Full Name], agree to the terms of the Contributor License Agreement
as outlined in CONTRIBUTING.md, dated [Current Date].

GitHub Username: @your_username
Date: YYYY-MM-DD

Include in Pull Request

Include this file in your pull request along with your code changes.

See existing contributor files in the /contributors/ directory for examples.

CLA Terms Summary

You grant Mempool and software recipients a perpetual, worldwide, non-exclusive, royalty-free, irrevocable copyright license to:

Reproduce your contributions
Prepare derivative works
Publicly display and perform
Sublicense and distribute

Patent License

You grant a perpetual, worldwide, non-exclusive, royalty-free, irrevocable patent license for any patent claims necessarily infringed by your contributions.

Originality

You represent that:

Each contribution is your original creation
You have permission to contribute (if employed)
You’ve disclosed any third-party licenses or restrictions

No Support Required

You are not expected to provide support for your contributions, except to the extent you desire.

The full CLA text is available in the CONTRIBUTING.md file in the repository.

Code Standards

TypeScript Style

Both frontend and backend use TypeScript with ESLint for code quality.

Backend
Frontend

cd backend

# Check for linting errors
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code with Prettier
npm run prettier

cd frontend

# Check for linting errors
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code with Prettier
npm run prettier

Commit Message Convention

Use conventional commit messages:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat(mining): add support for new mining pool detection

Implements automatic detection of XYZ mining pool using
coinbase transaction patterns.

Closes #123

GPG Signing

All commits must be GPG-signed. Pull requests with unsigned commits will not be merged.

Generate GPG Key

If you don’t have a GPG key:

gpg --full-generate-key

Choose:

Key type: RSA and RSA
Key size: 4096 bits
Expiration: Your preference

Add Key to GitHub

Export your public key:

gpg --armor --export YOUR_EMAIL

Add it to GitHub: Settings → SSH and GPG keys → New GPG key

Configure Git

git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true

Testing Requirements

All contributions must include appropriate tests.

Backend Tests

Unit Tests
Integration Tests
Coverage

Use Jest for unit tests:

// backend/src/__tests__/example.test.ts
describe('MyFunction', () => {
  it('should return expected result', () => {
    expect(myFunction(input)).toBe(expectedOutput);
  });
});

Run tests:

npm test

Integration tests require a database:

npm run test:integration

Ensure adequate test coverage:

npm run test:ci

Coverage reports are generated in coverage/.

Frontend Tests

Unit Tests
E2E Tests

Angular unit tests:

npm test

Cypress end-to-end tests:

# Interactive mode
npm run cypress:open

# Headless mode
npm run cypress:run

See the Testing Guide for detailed testing information.

Pull Request Process

Before Submitting

PR Description Template

Include in your pull request:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
Describe testing performed

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] Tests pass locally
- [ ] Commits are GPG-signed
- [ ] CLA agreement included (if first PR)

Review Process

Automated Checks

CI/CD runs automatically:

Linting
Type checking
Unit tests
Integration tests
E2E tests (frontend)

Code Review

Team members review your code:

Code quality
Test coverage
Design decisions
Documentation

Address Feedback

Make requested changes:

git add .
git commit -m "fix: address review feedback"
git push

Merge

Once approved, a maintainer will merge your PR.

Common Contribution Areas

Bug Fixes

Find bugs in GitHub Issues labeled bug

Feature Development

Check issues labeled enhancement or feature-request

Documentation

Improve docs, add examples, fix typos

Translations

Contribute translations via Transifex

Testing

Add test coverage for untested code

Performance

Identify and fix performance bottlenecks

Getting Help

GitHub Issues
Development Questions
Mempool Enterprise

Open an issue for:

Bug reports
Feature requests
Questions about contributing

View Issues →

Code of Conduct

Expected Behavior

Be respectful and inclusive
Welcome newcomers
Accept constructive criticism
Focus on what’s best for the community
Show empathy towards others

Unacceptable Behavior

Harassment or discrimination
Trolling or insulting comments
Personal or political attacks
Publishing others’ private information
Other unprofessional conduct

Attribution

Contributors are recognized in several ways:

Listed in the /contributors/ directory
Mentioned in release notes
Displayed on the About page
Git commit history

Next Steps

Setup Development Environment

Get your local environment ready

Architecture Overview

Understand the codebase structure

Testing Guide

Learn about testing practices

View Issues

Find something to work on

Get Started

Installation

Core Features

Configuration

Self-Hosting

Development

Documentation Index

​Before You Start

​Quick Start

​Contributor License Agreement

​First-Time Contributors

​CLA Terms Summary

​Code Standards

​TypeScript Style

​Commit Message Convention

​GPG Signing

​Testing Requirements

​Backend Tests

​Frontend Tests

​Pull Request Process

​Before Submitting

​PR Description Template

​Review Process

​Common Contribution Areas

Bug Fixes

Feature Development

Documentation

Translations

Testing

Performance

​Getting Help

​Code of Conduct

​Expected Behavior

​Unacceptable Behavior

​Attribution

​Next Steps

Setup Development Environment

Architecture Overview

Testing Guide

View Issues

Build docs developers (and LLMs) love

Before You Start

Quick Start

Contributor License Agreement

First-Time Contributors

CLA Terms Summary

Code Standards

TypeScript Style

Commit Message Convention

GPG Signing

Testing Requirements

Backend Tests

Frontend Tests

Pull Request Process

Before Submitting

PR Description Template

Review Process

Common Contribution Areas

Getting Help

Code of Conduct

Expected Behavior

Unacceptable Behavior

Attribution

Next Steps