# Contributing to Brave: Pull Request and Code Review Guidelines

> Learn how to contribute to Brave browser. Follow our guidelines for creating PRs, writing commits, and passing CI checks for efficient code reviews and integration.

- Repository: [Brave Software/brave-browser](https://github.com/brave/brave-browser)
- Tags: best-practices
- Published: 2026-02-16

---

**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`](https://github.com/brave/brave-browser/blob/main/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.

```bash

# 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`](https://github.com/brave/brave-browser/blob/main/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.

```javascript
// 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`](https://github.com/brave/brave-browser/blob/main/CONTRIBUTING.md) (lines 22‑28). The PR template (located at [`.github/pull_request_template.md`](https://github.com/brave/brave-browser/blob/main/.github/pull_request_template.md) if present) requires:

- **Descriptive title** following the pattern `Component: short description` (used for release notes in [`CHANGELOG_DESKTOP.md`](https://github.com/brave/brave-browser/blob/main/CHANGELOG_DESKTOP.md) and [`CHANGELOG_ANDROID.md`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/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.