Skip to main content

​
Before You Start

Before creating a pull request, make sure you’ve:
1

Read the guidelines

Familiarize yourself with the contribution guidelines and code style rules.
2

Create a feature branch

git checkout -b feature/your-feature-name
# Or for bug fixes:
git checkout -b fix/ISSUE-123-bug-description
3

Test locally

# Run linting and type checks
turbo run lint check-types

# Run tests
yarn workspace @proton/your-package test

​
Branch Naming Conventions

Use descriptive branch names that indicate the purpose of your changes: 
feature/add-dark-mode-toggle
feature/MAIL-123-attachment-preview
If working on an issue, include the issue/ticket number in the branch name for better traceability.

​
Commit Messages

​
Format

Write clear, descriptive commit messages: 
<type>: <description>

[optional body]

[optional footer]

​
Types

  • feat: New feature
  • fix: Bug fix
  • refactor: Code refactoring (no functional changes)
  • perf: Performance improvements
  • style: Code style changes (formatting, missing semicolons, etc.)
  • test: Adding or updating tests
  • docs: Documentation changes
  • chore: Maintenance tasks (dependencies, build config, etc.)

​
Examples

feat: add dark mode toggle to settings

Implements a new toggle in user settings that allows switching
between light and dark themes. The preference is saved to local
storage and persisted across sessions.

Closes #1234

​
Commit Standards

Important: All commits must pass pre-commit hooks before they can be committed. The hooks will automatically:
  • Run ESLint with zero warnings policy
  • Format code with Prettier
  • Lint SCSS files with Stylelint
  • Sort package.json files

​
Creating a Pull Request

​
1. Push Your Branch

git push origin feature/your-feature-name

​
2. Open a Pull Request

Go to github.com/ProtonMail/WebClients and click “New Pull Request”.

​
3. Fill Out the PR Template

Provide a clear description of your changes:
Write a concise, descriptive title:
✅ Good:
feat: Add dark mode toggle to user settings
fix: Resolve calendar timezone conversion bug

❌ Bad:
Updated settings
Fixed bug
Changes

​
PR Requirements

​
Automated Checks

Your PR must pass all automated checks:

Linting

ESLint must pass with zero warnings

Type Checking

TypeScript must compile without errors

Tests

All existing tests must pass

Build

Application must build successfully
The CI will automatically run these checks when you push commits or open a PR. Check the “Checks” tab on your PR for results.

​
Code Review

All pull requests require code review before merging:
  1. Self-review first - Review your own changes before requesting review
  2. Request reviewers - Tag relevant team members or maintainers
  3. Address feedback - Respond to all review comments
  4. Resolve conversations - Mark conversations as resolved once addressed

​
MergeBot Integration

This repository uses MergeBot (.margebot.yml) for automated merging: 
fastTrack:
  allowList:
    - maintainer-username
    # Core team members who can fast-track PRs
    
forbiddenTags:
  - state::Blocked
  
ciFailFast: true
  • PRs labeled with state::Blocked will not be auto-merged
  • CI failures will prevent merging (ciFailFast: true)
  • Some team members can fast-track PRs through the review process

​
Updating Your PR

​
Responding to Feedback

1

Make requested changes

# Make your changes
git add .
git commit -m "refactor: address review feedback"
2

Push updates

git push origin feature/your-feature-name
The PR will automatically update with your new commits.
3

Respond to comments

Reply to review comments explaining your changes or asking for clarification.

​
Keeping Your Branch Updated

If main has advanced since you created your branch: 
# Update your local main branch
git checkout main
git pull origin main

# Rebase your feature branch
git checkout feature/your-feature-name
git rebase main

# Force push if already pushed
git push origin feature/your-feature-name --force-with-lease
Use --force-with-lease instead of --force to avoid accidentally overwriting others’ work.

​
PR Size Guidelines

Lines changed: < 300✅ Benefits:
  • Faster to review
  • Easier to understand
  • Lower risk of bugs
  • Quicker to merge
Examples:
  • Single bug fix
  • Small feature addition
  • Documentation update
  • Dependency update

​
Common PR Issues

Make sure you’ve run linting locally:
turbo run lint
Fix all warnings and errors. Remember: --max-warnings=0 is enforced.
Run type checking locally:
turbo run check-types
Fix all TypeScript errors before pushing.
Rebase your branch on the latest main:
git checkout main
git pull origin main
git checkout your-branch
git rebase main
# Resolve conflicts
git push origin your-branch --force-with-lease
The pre-commit hooks run:
  • ESLint with --fix
  • Prettier with --write
  • Stylelint with --fix
Let them auto-fix what they can, then stage and commit again.If hooks aren’t running at all:
yarn husky
Run tests locally to debug:
yarn workspace @proton/your-package test

# Run specific test file
yarn workspace @proton/your-package test path/to/test.spec.ts

​
After Your PR is Merged

1

Update your local repository

git checkout main
git pull origin main
2

Delete your feature branch

# Delete local branch
git branch -d feature/your-feature-name

# Delete remote branch (if not auto-deleted)
git push origin --delete feature/your-feature-name
3

Celebrate!

🎉 Your contribution is now part of Proton WebClients!

​
PR Review Guidelines

​
For Reviewers

If you’re reviewing a PR:
  • Code follows style guidelines
  • Logic is clear and maintainable
  • No unnecessary complexity
  • Tests cover new functionality
  • No security vulnerabilities
  • Performance impact is acceptable
  • Backwards compatibility maintained
  • Documentation is updated

​
Resources

GitHub Issues

Browse existing issues or report new ones

Contribution Guidelines

General guidelines for contributing

Code Style Guide

Linting and formatting standards

Yarn Workspaces

Learn about monorepo management

​
Getting Help

Use the Ask a Question issue template for:
  • Code-related questions
  • Technical discussions
  • Implementation advice
Thank you for contributing to Proton WebClients! Your efforts help make privacy and security accessible to everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us