| # 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][gerrit]{:.external} web UI. When a commit is uploaded |
| to Gerrit, it is referred to as a [change][gerrit-changes]{:.external}. |
| |
| To contribute a change to Fuchsia, the steps are: |
| |
| 1. [Prerequisites](#prerequisites). |
| 1. [Create a change in Gerrit](#create-a-change-in-gerrit). |
| 1. [Request a code review](#request-a-code-review). |
| 1. [Track your code review](#track-your-code-review). |
| 1. [Submit your change](#submit-your-change). |
| |
| ## 1. Prerequisites {#prerequisites} |
| |
| Before you begin, you need to: |
| |
| * [Download the Fuchsia source code](/docs/get-started/get_fuchsia_source.md). |
| |
| Note: You can complete the next prerequisite items while downloading the |
| Fuchsia source code. |
| |
| * [Sign the Google Contributor License Agreements (CLA)](#sign-the-google-cla). |
| * [Generate a cookie to authenticate you in Gerrit](#generate-a-cookie). |
| |
| ### Sign the Google CLA {#sign-the-google-cla} |
| |
| Do the following: |
| |
| 1. Go to the Google Developers' |
| [Contributor License Agreements](https://cla.developers.google.com/){:.external} |
| page. |
| 1. Sign the agreement on behalf of **Only Yourself** or **Your Employer**. |
| |
| ### Generate a cookie {#generate-a-cookie} |
| |
| Do the following: |
| |
| 1. Log into [Gerrit][gerrit]{:.external}. |
| 1. Go to |
| [https://fuchsia.googlesource.com](https://fuchsia.googlesource.com){:.external}. |
| 1. At the top of the page, click **Generate Password**. |
| 1. Copy the generated code and run it in a terminal of your workstation. |
| |
| ## 2. Create a change in Gerrit {#create-a-change-in-gerrit} |
| |
| To create a change in Gerrit, do the following: |
| |
| 1. Go to your Fuchsia directory, for example: |
| |
| ```posix-terminal |
| cd ~/fuchsia |
| ``` |
| |
| 1. Create a new branch: |
| |
| ```posix-terminal |
| git checkout -b <branch_name> |
| ``` |
| |
| 1. Create or edit files in the new branch. |
| |
| 1. Add the updated files: |
| |
| ```posix-terminal |
| git add <files> |
| ``` |
| |
| 1. Commit the updated files and write the [commit message][commit-message-style-guide]: |
| |
| ```posix-terminal |
| git commit |
| ``` |
| |
| 1. Upload the commit to Gerrit: |
| |
| ```posix-terminal |
| git push origin HEAD:refs/for/main |
| ``` |
| |
| For more information on uploading changes, see the |
| [Gerrit documentation][gerrit-doc-upload-change]{:.external}. |
| |
| ## 3. Request a code review {#request-a-code-review} |
| |
| After creating a change, to request a code review, do the following: |
| |
| 1. Go to your [Fuchsia Gerrit dashboard](https://fuchsia-review.googlesource.com/dashboard/self). |
| 1. Click your change, which appears in the *Outgoing reviews* section. |
| 1. Click **ADD REVIEWER**. |
| 1. 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. |
| |
| 1. Click **SEND**. |
| |
| ## 4. Track your code review {#track-your-code-review} |
| |
| To track the progress of your code review, use Gerrit's [web UI][gerrit]{:.external}. |
| (For more information on using the Gerrit code review tool, see |
| [Review UI][user-review-ui]{:.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][config-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. |
| |
| If you need to update your change during the review process, see |
| [Create and upload a patch](#create-and-upload-a-patch) (or |
| [Resolve merge conflicts](#resolve-merge-conflicts)) in Appendices. |
| |
| ### Resolve comments {#resolving-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 {#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][committer] |
| to submit code for them. |
| |
| ## Appendices |
| |
| ### Create and upload a patch {#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. |
| 1. Add the updated files: |
| |
| ```posix-terminal |
| git add <updated_files> |
| ``` |
| |
| 1. Include the patch in the same commit using the `--amend` option: |
| |
| ```posix-terminal |
| git commit --amend |
| ``` |
| |
| 1. Upload the patch to Gerrit: |
| |
| ```posix-terminal |
| git push origin HEAD:refs/for/main |
| ``` |
| |
| ### 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: |
| |
| ```posix-terminal |
| git rebase origin/main |
| ``` |
| |
| 1. Edit those files to resolve the conflicts and add the updated files: |
| |
| ```posix-terminal |
| git add <files_with_resolved_conflicts> |
| ``` |
| |
| 1. Finish the rebase: |
| |
| ```posix-terminal |
| git rebase --continue |
| ``` |
| |
| 1. Commit the updated files using the `--amend` option: |
| |
| ```posix-terminal |
| git commit --amend |
| ``` |
| |
| 1. Upload the patch to Gerrit: |
| |
| ```posix-terminal |
| git push origin HEAD:refs/for/main |
| ``` |
| |
| ### Delete your local branch {#delete-your-local-branch} |
| |
| After the change is submitted, you may delete your local branch: |
| |
| ```posix-terminal |
| git branch -d <branch_name> |
| ``` |
| |
| ### Write a change message {#write-a-change-message} |
| |
| When writing a change message, follow the [Commit message style |
| guide](/docs/contribute/commit-message-style-guide.md). |
| |
| ### Manage changes that span multiple repositories {#manage-changes-that-span-multiple-repos} |
| |
| To understand how to manage changes that span different repositories (petals), |
| see the following pages: |
| |
| * [Working across different petals](/docs/development/source_code/working_across_petals.md) |
| * [Upload changes from multiple repositories](/docs/development/source_code/upload_changes_from_multiple_repositories.md) |
| |
| See [Source code layout](/docs/development/source_code/layout.md) for more |
| information on the structure of the Fuchsia repository. |
| |
| |
| <!-- Reference links --> |
| |
| [gerrit]: https://fuchsia-review.googlesource.com |
| [gerrit-changes]: https://gerrit-review.googlesource.com/Documentation/concept-changes.html |
| [commit-message-style-guide]: /docs/contribute/commit-message-style-guide.md |
| [gerrit-doc-upload-change]: https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html#upload-change |
| [user-review-ui]: https://gerrit-review.googlesource.com/Documentation/user-review-ui.html |
| [config-labels]: https://gerrit-review.googlesource.com/Documentation/config-labels.html |
| [committer]: /docs/contribute/community/contributor-roles.md#committer |