Contribute changes

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

Prerequisites

Fuchsia manages commits through Gerrit{:.external}.

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

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.

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 these guidelines:

Add commit message tags
Add test instructions

Add commit message tags

Include [tags] in the subject of a commit message to indicate which module, library, and app are affected by your change. For instance, use [docs] for documentation, [zircon] for zircon, and [fidl] for FIDL.

The following example of a commit message shows the tags in the subject:

You can view the commit history of the files you've edited to check for the tags used previously. See these examples:

https://fuchsia-review.googlesource.com/c/peridot/+/113955{:.external}
https://fuchsia-review.googlesource.com/c/topaz/+/114013{:.external}

If the subject of a commit message doesn't include tags, Gerrit flags your change with Needs Label: Commit-Message-has-tags.

Add test instructions

If a change requires non-obvious manual testing for validation, describe those testing steps in the change description beginning with Test:, for example:

Test: Write the test instructions here.

If the instructions are complex, create a bug and provide a link to that bug in the change description. If the change doesn't intend to change behavior, indicate that fact in the commit message.

In some cases, certain behavior changes cannot be tested because Fuchsia lacks some particular piece of infrastructure. If so, create an issue in the tracker about the necessary infrastructure support and provide the bug number in the change description, in addition to describing how the change is tested manually, for example:

Test: Manually tested that [...]. Automated testing needs US-XXXX.

Developers are responsible for high-quality automated testing of their code. Reviewers are responsible for pushing back on changes that do not include sufficient tests. See Fuchsia testability rubrics for more information on how to introduce testable and tested code in the Fuchsia project.

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.