Contribute changes

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

Prerequisites

Fuchsia manages git commits and code reviews through Gerrit's{:.external} web UI.

Before you begin, you need to:

Download the Fuchsia source code.
Note: You can complete the next prerequisite items while downloading the Fuchsia source code.
Sign the Google Contributor License Agreements (CLA).
Generate a cookie to authenticate you in Gerrit.

Sign the Google CLA

Do the following:

Go to the Google Developers' Contributor License Agreements{:.external} page.
Sign the agreement on behalf of Only Yourself or Your Employer.

Generate a cookie

Do the following:

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

Create a change in Gerrit

The Fuchsia project uses Gerrit's web-based UI to manage code and documentation reviews. When a commit is uploaded to Gerrit, it is referred to as as a change.

To create a change{:.external} in Gerrit, do the following:

Go to your Fuchsia directory, for example:
```
cd ~/fuchsia
```
Create a new branch:
```
git checkout -b <branch_name>
```
Create or edit files in the new branch.
Add the updated files:
```
git add <files>
```
Commit the updated files and write a change message:
```
git commit
```
Upload the commit to Gerrit:
```
jiri upload
```
If you want to use the git command instead, run the following command:
```
git push origin HEAD:refs/for/master
```

See the Gerrit documentation{:.external} for more information.

Request a code review

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

Go to your Fuchsia Gerrit dashboard.
Click your change, which appears in the Outgoing reviews section.
Click ADD REVIEWER.
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.
Click SEND.

Track your review

To track the progress of your code review, use Gerrit{:.external}. For more information on how to use the Gerrit code review tool, see Review UI documentation{:.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{:.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.

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 to submit code for them.

Create and upload a patch

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

Create or edit files in the same branch.
Add the updated files:
```
git add <files>
```
Include the patch in the same commit using the --amend option:
```
git commit --amend
```
Upload the patch to Gerrit:
```
jiri upload
```

Resolve merge conflicts

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

Rebase from origin/master, which reveals the files that cause merge conflicts:
```
git rebase origin/master
```

Edit those files to resolve the conflicts and finish the rebase:

git add <files_with_resolved_conflicts>

git rebase --continue

Upload the patch to your change:
```
git commit --amend
```
```
jiri upload
```

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.

Contribute a change to the API

To contribute to the Fuchsia API Surface, do the following:

Evaluate whether your change is large or small.
- If you have a small, incremental change to the API, contribute your change by completing the steps in create a change in Gerrit, as you would for any Fuchsia source code change.
- If you have a large change to the API, that is, a change that significantly expands on the fuction of the API or modifies the API extensively, do the following:
  - Create an API Design Document that explains the design of your modification to the API.
  - Request a review of your API Design Document. To read about the API Design Document and the API Design Document review process, see Decision process in the Fuchsia API Council Charter.
  - After your API Design Document is approved, contribute your change by completing the steps in create a change in Gerrit, as you would for any Fuchsia source code change.
Request a code review from an API council member. Select your API council reviewer based on the area of the Fuchsia API that you're modifying. For a list of API council members and their areas of focus, see Membership in the Fuchsia API Council Charter.

Manage changes that span multiple repositories

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

See Source code layout for more information on the structure of the Fuchsia repository.