docs/development/source_code/contribute_changes.md

# 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][gerrit]{:.external} web UI. 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.  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}.

## 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
[Create and upload a patch](#create-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

### Create and upload a patch {#create-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.  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.  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
[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