# 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][gerrit]{:.external}. When a commit is uploaded to Gerrit,
it is referred to as a [change][gerrit-changes]{:.external}.

To contribute a change to Fuchsia, the steps are:

1. [Prerequisites](#prerequisites).
1. [Create a change in Gerrit](#create-a-change-in-gerrit).
1. [Request a code review](#request-a-code-review).
1. [Track your code review](#track-your-code-review).
1. [Submit your change](#submit-your-change).

## 1. Prerequisites {#prerequisites}

Before you begin, you need to:

* [Download the Fuchsia source code](/docs/get-started/get_fuchsia_source.md).

  Note: You can complete the next prerequisite items while downloading the
  Fuchsia source code.

* [Sign the Google Contributor License Agreements (CLA)](#sign-the-google-cla).
* [Generate a cookie to authenticate you in Gerrit](#generate-a-cookie).

### Sign the Google CLA {#sign-the-google-cla}

Do the following:

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

### Generate a cookie {#generate-a-cookie}

Do the following:

1. Log into [Gerrit][gerrit]{:.external}.
1. Go to
   [https://fuchsia.googlesource.com](https://fuchsia.googlesource.com){:.external}.
1. At the top of the page, click **Generate Password**.
1. Copy the generated code and run it in a terminal of your workstation.

## 2. Create a change in Gerrit {#create-a-change-in-gerrit}

To create a change in Gerrit, do the following:

1. Go to your Fuchsia directory, for example:

   ```posix-terminal
   cd ~/fuchsia
   ```

1. Create a new branch:

   ```posix-terminal
   git checkout -b <branch_name>
   ```

1. Create or edit files in the new branch.

1. Format modified or newly added code.

   ```posix-terminal
   fx format-code
   ```

   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][permission-errors-on-Ubuntu-24.x-systems]{:.external}.

1. Add the updated files:

   ```posix-terminal
   git add <files>
   ```

1. Commit the updated files and write the [commit message][commit-message-style-guide]:

   ```posix-terminal
   git commit
   ```

1. Upload the commit to Gerrit:

   ```posix-terminal
   git push origin HEAD:refs/for/main
   ```

   For more information on uploading changes, see the
   [Gerrit documentation][gerrit-doc-upload-change]{:.external}.

   For more information on special options that control commit behavior, see
   [Commit message options][commit-message-options]{:.external}.

## 3. Request a code review {#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).
1. Click your change, which appears in the *Outgoing reviews* section.
1. Click **ADD REVIEWER**.
1. 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][owners].

1. Click **SEND**.

## 4. Track your code review {#track-your-code-review}

To track the progress of your code review, use Gerrit's [web UI][gerrit]{:.external}.
(For more information on using the Gerrit code review tool, see
[Review UI][user-review-ui]{:.external}.)

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][config-labels]{:.external}).
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](#update-and-upload-a-patch) (or
[Resolve merge conflicts](#resolve-merge-conflicts)) in Appendices.

### Resolve comments {#resolving-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 {#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][committer]
to submit code for them.

## Appendices

### Update and upload a patch {#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.

1. Format the files that you have updated:

   ```posix-terminal
   fx format-code
   ```

1. Add the updated files:

   ```posix-terminal
   git add <updated_files>
   ```

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

   ```posix-terminal
   git commit --amend
   ```

1. Upload the patch to Gerrit:

   ```posix-terminal
   git push origin HEAD:refs/for/main
   ```

### Resolve merge conflicts {#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:

   ```posix-terminal
   git rebase origin/main
   ```

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

   ```posix-terminal
   git add <files_with_resolved_conflicts>
   ```

1. Format the files:

   ```posix-terminal
   fx format-code
   ```

1. Finish the rebase:

   ```posix-terminal
   git rebase --continue
   ```

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

   ```posix-terminal
   git commit --amend
   ```

1. Upload the patch to Gerrit:

   ```posix-terminal
   git push origin HEAD:refs/for/main
   ```

### Delete your local branch {#delete-your-local-branch}

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

```posix-terminal
git branch -d <branch_name>
```

### Write a change message {#write-a-change-message}

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

### Manage changes that span multiple repositories {#manage-changes-that-span-multiple-repos}

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

* [Working across different petals](/docs/development/source_code/working_across_petals.md)
* [Upload changes from multiple repositories](/docs/development/source_code/upload_changes_from_multiple_repositories.md)

See [Source code layout](/docs/development/source_code/layout.md) for more
information on the structure of the Fuchsia repository.

<!-- Reference links -->

[gerrit]: https://fuchsia-review.googlesource.com
[gerrit-changes]: https://gerrit-review.googlesource.com/Documentation/concept-changes.html
[commit-message-style-guide]: /docs/contribute/commit-message-style-guide.md
[commit-message-options]: /docs/development/source_code/commit_message_options.md
[gerrit-doc-upload-change]: https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html#upload-change
[user-review-ui]: https://gerrit-review.googlesource.com/Documentation/user-review-ui.html
[config-labels]: https://gerrit-review.googlesource.com/Documentation/config-labels.html
[committer]: /docs/contribute/community/contributor-roles.md#committer
[owners]: /docs/development/source_code/owners.md
[permission-errors-on-Ubuntu-24.x-systems]: https://github.com/google/nsjail/issues/236