Skip to content

Latest commit

 

History

History
298 lines (206 loc) · 9.87 KB

contribute_changes.md

File metadata and controls

298 lines (206 loc) · 9.87 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 a change message:

    git commit

  6. 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:

  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 master 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/master, which reveals the files that cause merge conflicts:

    git rebase origin/master

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

Add commit message tags {#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:

[parent][component] Update component in Topaz.

Write the details of a commit message here.

Test: Added test X.

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

Commit message tags are required. 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 {#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.

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.