Contributing to Brave: Pull Request and Code Review Guidelines

To contribute to Brave, create a descriptive feature branch, write logical commits with accompanying tests, complete the PR template with issue references, and ensure all CI checks pass before requesting review from core maintainers.

The brave/brave-browser repository welcomes community contributions through a structured workflow defined in CONTRIBUTING.md. This guide covers the complete lifecycle of contributing to Brave, from branch creation to post-merge uplifts, ensuring your changes meet the project's quality standards and coding conventions.

Preparing a Pull Request for Brave

Branch Naming and Commit Standards

Start by forking the repository and cloning your fork locally. According to CONTRIBUTING.md (lines 79‑80), you must create a new branch with a descriptive name such as fix-fullscreen-issue or feature-shields-v2.

Write logical, atomic commits that can be squashed if necessary before opening the PR. The guidelines (lines 80‑81) emphasize making commits in logical units to maintain a clean history.

# Clone your fork

git clone https://github.com/yourname/brave-browser.git
cd brave-browser

# Add upstream remote

git remote add upstream https://github.com/brave/brave-browser.git
git fetch upstream

# Create feature branch

git checkout -b fix-fullscreen-issue upstream/master

# Commit changes

git add .
git commit -m "fix(fullscreen): correct window sizing on macOS

Fixes #1234

Tested on macOS 13.2 – open a fullscreen window and verify size."

Testing Requirements

New features and most bug fixes require tests. As documented in CONTRIBUTING.md (lines 81‑82), you must add tests for new functionality unless the change is purely documentation or UI-related with no logic changes.

Manually test your changes on your target platform before submitting. The contribution guide specifically asks, "Did you manually test your new change?" (lines 16‑17) to catch regressions early.

// Example unit test for JavaScript components
import { getFullscreenSize } from 'brave/ui/fullscreen';

describe('Fullscreen size calculation', () => {
  it('returns screen dimensions on macOS', () => {
    const size = getFullscreenSize({ platform: 'darwin' });
    expect(size.width).toBe(screen.width);
    expect(size.height).toBe(screen.height);
  });
});

PR Template and Metadata

Every pull request must include specific metadata as outlined in CONTRIBUTING.md (lines 22‑28). The PR template (located at .github/pull_request_template.md if present) requires:

• Descriptive title following the pattern Component: short description (used for release notes in CHANGELOG_DESKTOP.md and CHANGELOG_ANDROID.md)
• Summary explaining what and why
• Issue references using Fixes #1234 for automatic closing
• Test steps or screenshots for UI changes
• Labels such as Bug, Feature, or Good first issue

Tag reviewers once submitted. According to lines 29‑30, you should tag reviewers to notify them, though the system may auto-assign based on code ownership.

Title: fix(fullscreen): correct window sizing on macOS

Summary
-------
Fixes a regression where fullscreen windows were rendered at an incorrect size on macOS 13.

Issue
-----
Fixes #1234

Test Steps
----------
1. Build Brave from source.
2. Open a window and enter fullscreen mode.
3. Verify that the window dimensions match the screen size.

Screenshots
-----------
N/A (behavior is visual)

Labels
------
- Bug
- macOS
- Good first issue

The Brave Code Review Process

Reviewer Responsibilities

Code reviews in Brave follow a structured protocol defined in CONTRIBUTING.md (lines 31‑34). Employee reviewers must:

• Assign the owner to establish clear responsibility
• Add at least one other reviewer to ensure multiple perspectives
• Complete the checklist in the PR template

Reviewers verify that changes meet functional requirements, follow coding standards (StandardJS for JavaScript, clang‑format for C++), include adequate tests, and do not introduce regressions. Contributors should respond to comments promptly, pushing follow‑up commits to the same branch and updating the PR description if the scope changes.

Automated CI Checks

Brave's continuous integration runs automatically on every pull request. The CI pipeline executes unit tests, browser tests, and JavaScript tests using commands like npm run test.

The PR cannot be merged until all required checks pass. This ensures that changes in src/brave/ (core JavaScript/React UI) and src/brave/**/*.cpp (C++ components) meet quality gates before reaching the master branch.

Post-Merge Workflow

Once a pull request is merged, the associated issue automatically receives the appropriate milestone (nightly/master) according to CONTRIBUTING.md (lines 38‑39).

If the change needs to be uplifted to other release channels (Dev, Beta, or Release), contributors must follow the process documented in the "Uplifting a pull request" wiki page. This ensures critical fixes reach stable versions while maintaining the integrity of the release cycle.

Summary

• Branching: Create descriptive branches from upstream master and write logical, atomic commits.
• Testing: Add tests for new functionality and manually verify changes before submitting.
• Documentation: Complete the PR template with descriptive titles, summaries, issue references (Fixes #xxxx), and appropriate labels.
• Review: Tag reviewers, respond to feedback promptly, and ensure employee reviewers assign owners and complete checklists.
• Quality Gates: All CI checks must pass before merging, enforcing StandardJS and clang‑format compliance.
• Post-Merge: Issues receive milestones automatically; use the uplift wiki for back‑porting to stable channels.

Frequently Asked Questions

What coding standards does Brave enforce for contributions?

Brave enforces StandardJS for JavaScript code and clang‑format for C++ components. These standards are verified through automated CI checks that run on every pull request. Contributors should ensure their code in src/brave/ (JavaScript/React) and src/brave/**/*.cpp (C++) complies with these formatting rules before requesting review.

How do I reference issues in my Brave pull request?

Include the issue reference in your PR description using the format Fixes #1234 (replacing 1234 with the actual issue number). According to CONTRIBUTING.md (lines 22‑28), this syntax ensures the issue automatically closes when the PR merges. You should also mention the issue number in your commit messages for traceability.

What happens after my Brave pull request is merged?

Once merged, the associated issue automatically receives the appropriate milestone (nightly or master) as documented in CONTRIBUTING.md (lines 38‑39). If your fix needs to reach stable release channels (Dev, Beta, or Release), you must follow the "Uplifting a pull request" wiki process to back‑port the change safely.

Who can review my pull request to Brave?

Employee reviewers must assign an owner, add at least one additional reviewer, and complete the PR template checklist according to CONTRIBUTING.md (lines 31‑34). While core team members typically handle final approval, experienced community contributors may also provide review feedback. You should tag specific reviewers when opening the PR to notify them of pending changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}