# Contribute changes

This guide provides instructions on how to submit your contribution to the
Fuchsia project.

Fuchsia manages git commits and code reviews through Gerrit's
[web UI](https://fuchsia-review.googlesource.com). When a commit is uploaded to Gerrit,
it is referred to as a [change](https://gerrit-review.googlesource.com/Documentation/concept-changes.html).

To contribute a change to Fuchsia, the steps are:

1. [Prerequisites](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#prerequisites).
2. [Create a change in Gerrit](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#create-a-change-in-gerrit).
3. [Request a code review](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#request-a-code-review).
4. [Track your code review](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#track-your-code-review).
5. [Submit your change](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#submit-your-change).

## 1. Prerequisites

Before you begin, you need to:

- [Download the Fuchsia source code](https://fuchsia.dev/docs/get-started/get_fuchsia_source).

  > [!NOTE]
  > **Note:** You can complete the next prerequisite items while downloading the Fuchsia source code.

- [Sign the Google Contributor License Agreements (CLA)](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#sign-the-google-cla).

- [Generate a cookie to authenticate you in Gerrit](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#generate-a-cookie).

### Sign the Google CLA

Do the following:

1. Go to the Google Developers' [Contributor License Agreements](https://cla.developers.google.com/) page.
2. Sign the agreement on behalf of **Only Yourself** or **Your Employer**.

### Generate a cookie

Do the following:

1. Log into [Gerrit](https://fuchsia-review.googlesource.com).
2. Go to <https://fuchsia.googlesource.com>.
3. At the top of the page, click **Generate Password**.
4. Copy the generated code and run it in a terminal of your workstation.

## 2. Create a change in Gerrit

To create a change in Gerrit, do the following:

1. Go to your Fuchsia directory, for example:

       cd ~/fuchsia

2. Create a new branch:

       git checkout -b <branch_name>

3. Create or edit files in the new branch.

4. Format modified or newly added code.

       fx format-code

   > [!NOTE]
   > **Note:** On some Ubuntu 24.x systems, you may see an error like `initCloneNs():382 mount('/', '/', NULL, MS_REC|MS_PRIVATE, NULL): Permission denied` when executing `fx format-code`. These errors are caused by the system's AppArmor configuration. For a workaround, see [permission errors on Ubuntu 24.x systems](https://github.com/google/nsjail/issues/236).

5. Add the updated files:

       git add <files>

6. Commit the updated files and write the [commit message](https://fuchsia.dev/docs/contribute/commit-message-style-guide):

       git commit

7. Upload the commit to Gerrit:

       git push origin HEAD:refs/for/main

   For more information on uploading changes, see the
   [Gerrit documentation](https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html#upload-change).

   For more information on special options that control commit behavior, see
   [Commit message options](https://fuchsia.dev/docs/development/source_code/commit_message_options).

## 3. Request a code review

After creating a change, to request a code review, do the following:

1. Go to your [Fuchsia Gerrit dashboard](https://fuchsia-review.googlesource.com/dashboard/self).
2. Click your change, which appears in the *Outgoing reviews* section.
3. Click **ADD REVIEWER**.
4. Add reviewers by email address.

   You can refer to the `OWNERS` file, located in the directory where
   you're making your change or in one of its parents to find the best
   reviewers for your change. For more information about Fuchsia
   OWNERS, see [OWNERS](https://fuchsia.dev/docs/development/source_code/owners).
5. Click **SEND**.

## 4. Track your code review

To track the progress of your code review, use Gerrit's [web UI](https://fuchsia-review.googlesource.com).
(For more information on using the Gerrit code review tool, see
[Review UI](https://gerrit-review.googlesource.com/Documentation/user-review-ui.html).)

After you request a code review for your change, reviewers can score
your change. Reviewers can label your change with a
score of -2, -1, 0, +1, or +2. (For more information on
review label definitions see [Gerrit Code Review - Review Labels](https://gerrit-review.googlesource.com/Documentation/config-labels.html)).
In order for your change to be submitted, you need a **Code Review Label +2**.
A Code Review Label +2 score can only be applied by a directory owner.

If you need to update your change during the review process, see
[Update and upload a patch](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#update-and-upload-a-patch) (or
[Resolve merge conflicts](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#resolve-merge-conflicts)) in Appendices.

### Resolve comments

Your reviewers will probably leave comments describing things that
you need to update in your code before they can approve your change.
In general, only check the **Resolved** checkbox next to a comment when
you are sure that your reviewer will find your updates acceptable. If
there is any doubt whether your reviewer will agree with your updates,
leave the **Resolved** checkbox unchecked.

## 5. Submit your change

A change can be submitted after a repository owner applies the
**Code Review Label +2** to your change. When a change is submitted, the change
is submitted to the Commit Queue (CQ). The Commit Queue verifies and
merges changes to the `main` branch.

**Only contributors with commit access** can submit code directly through
the Gerrit interface. Regular members need to ask a [Committer](https://fuchsia.dev/docs/contribute/community/contributor-roles#committer)
to submit code for them.

## Appendices

### Update and upload a patch

After creating a change, to upload a patch to your change, do the following:

1. Create or edit files in the same branch.

2. Format the files that you have updated:

       fx format-code

3. Add the updated files:

       git add <updated_files>

4. Include the patch in the same commit using the `--amend` option:

       git commit --amend

5. Upload the patch to Gerrit:

       git push origin HEAD:refs/for/main

### Resolve merge conflicts

When Gerrit warns you of merge conflicts in your change, do the following:

1. Rebase from `origin/main`, which reveals the files that cause merge
   conflicts:

       git rebase origin/main

2. Edit those files to resolve the conflicts and add the updated files:

       git add <files_with_resolved_conflicts>

3. Format the files:

       fx format-code

4. Finish the rebase:

       git rebase --continue

5. Commit the updated files using the `--amend` option:

       git commit --amend

6. Upload the patch to Gerrit:

       git push origin HEAD:refs/for/main

### Delete your local branch

After the change is submitted, you may delete your local branch:

    git branch -d <branch_name>

### Write a change message

When writing a change message, follow the [Commit message style
guide](https://fuchsia.dev/docs/contribute/commit-message-style-guide).

### Manage changes that span multiple repositories

To understand how to manage changes that span different repositories (petals),
see the following pages:

- [Working across different petals](https://fuchsia.dev/docs/development/source_code/working_across_petals)
- [Upload changes from multiple repositories](https://fuchsia.dev/docs/development/source_code/upload_changes_from_multiple_repositories)

See [Source code layout](https://fuchsia.dev/docs/development/source_code/layout) for more
information on the structure of the Fuchsia repository.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/source_code/contribute_changes.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/source_code/contribute_changes.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/source_code/contribute_changes.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/source_code/contribute_changes.md "Edit the source code of this page")