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. When a commit is uploaded to Gerrit, it is referred to as a change.

To contribute a change to Fuchsia, the steps are:

1. Prerequisites.
2. Create a change in Gerrit.
3. Request a code review.
4. Track your code review.
5. Submit your change.

1. Prerequisites

Before you begin, you need to:

• Download 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:

1. Go to the Google Developers' Contributor License Agreements page.
2. Sign the agreement on behalf of Only Yourself or Your Employer.

Generate a cookie

Do the following:

1. Log into Gerrit.
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
   

5. Add the updated files:

   git add <files>
   

6. Commit the updated files and write the commit message:

   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.

   For more information on special options that control commit behavior, see 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.
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.

5. Click SEND.

4. Track your code review

To track the progress of your code review, use Gerrit's web UI. (For more information on using the Gerrit code review tool, see Review UI.)

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). 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 (or 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 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.

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
• Upload changes from multiple repositories

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