Skip to content

Latest commit

 

History

History
247 lines (171 loc) · 7.9 KB

contribute_changes.md

File metadata and controls

247 lines (171 loc) · 7.9 KB
Raw

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:

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

Do the following:

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

Generate a cookie {#generate-a-cookie}

Do the following:

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

Create a change in Gerrit {#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:

  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. Add the updated files:

    git add <files>

  5. Commit the updated files and write the change message:

    git commit

  6. Upload the commit to Gerrit:

You can use jiri or git.

jiri is a tool for working with multiple repositories that is installed with Fuchsia. To upload your commit:

jiri upload

See also the Jiri documentation for more information.

If you want to use the git command instead, run the following command:

git push origin HEAD:refs/for/main

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

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.
  5. 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 {#submit-a-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:

  1. Create or edit files in the same branch.

  2. Add the updated files:

    git add <files>

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

    git commit --amend

  4. Upload the patch to Gerrit:

    jiri upload

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:

    git rebase origin/main

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

    git add <files_with_resolved_conflicts>

    git rebase --continue

  3. 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 {#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 RFC that explains the design of your modification to the API.
      • This RFC should be reviewed through the normal RFC process. The API reviewer for the relevant area should be a stakeholder in the RFC. See the Fuchsia API Council Charter to identify API reviewers.
      • After your API RFC 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.