diff options
Diffstat (limited to 'docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md')
| -rw-r--r-- | docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md | 148 |
1 files changed, 70 insertions, 78 deletions
diff --git a/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md b/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md index 42f39f4..671c685 100644 --- a/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md +++ b/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md @@ -3,23 +3,21 @@ title: Gerrit Recommended Practices --- This document presents some best practices to help you use Gerrit more -effectively. The intent is to show how content can be submitted easily. -Use the recommended practices to reduce your troubleshooting time and -improve participation in the community. +effectively. The intent is to show how content can be submitted easily. Use the +recommended practices to reduce your troubleshooting time and improve +participation in the community. ## Commit Messages -Gerrit follows the Git commit message format. Ensure the headers are at -the bottom and don't contain blank lines between one another. The -following example shows the format and content expected in a commit -message: +Gerrit follows the Git commit message format. Ensure the headers are at the +bottom and don't contain blank lines between one another. The following example +shows the format and content expected in a commit message: Brief (no more than 50 chars) one line description. -Elaborate summary of the changes made referencing why (motivation), what -was changed and how it was tested. Note also any changes to -documentation made to remain consistent with the code changes, wrapping -text at 72 chars/line. +Elaborate summary of the changes made referencing why (motivation), what was +changed and how it was tested. Note also any changes to documentation made to +remain consistent with the code changes, wrapping text at 72 chars/line. ```sh Bug-AGL: SPEC-<JIRA-ID> @@ -28,52 +26,50 @@ Change-Id: LONGHEXHASH Signed-off-by: Your Name your.email\@example.org ``` -The Gerrit server provides a precommit hook to autogenerate the -Change-Id which is one time use. +The Gerrit server provides a precommit hook to autogenerate the Change-Id which +is one time use. -**Recommended reading:** [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/). +**Recommended reading:** [How to Write a Git Commit +Message](http://chris.beams.io/posts/git-commit/). ## Avoid Pushing Untested Work to a Gerrit Server To avoid pushing untested work to Gerrit. -Check your work at least three times before pushing your change to -Gerrit. Be mindful of what information you are publishing. +Check your work at least three times before pushing your change to Gerrit. Be +mindful of what information you are publishing. ## Keeping Track of Changes - Set Gerrit to send you emails: - Gerrit will add you to the email distribution list for a change if a - developer adds you as a reviewer, or if you comment on a specific - Patch Set. + developer adds you as a reviewer, or if you comment on a specific Patch Set. -- Opening a change in Gerrit's review interface is a quick way to - follow that change. +- Opening a change in Gerrit's review interface is a quick way to follow that + change. -- Watch projects in the Gerrit projects section at ``Gerrit``, select - at least *New Changes, New Patch Sets, All Comments* and *Submitted - Changes*. +- Watch projects in the Gerrit projects section at ``Gerrit``, select at least + *New Changes, New Patch Sets, All Comments* and *Submitted Changes*. -Always track the projects you are working on; also see the -feedback/comments [mailing list](https://lists.automotivelinux.org/g/agl-dev-community) -to learn and help others ramp up. +Always track the projects you are working on; also see the feedback/comments +[mailing list](https://lists.automotivelinux.org/g/agl-dev-community) to learn +and help others ramp up. ## Topic branches Topic branches are temporary branches that you push to commit a set of logically-grouped dependent commits: -To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed -as a topic in **TopicName** use the following command as an example: +To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed as a +topic in **TopicName** use the following command as an example: ```sh $ git push REMOTE HEAD:refs/for/master/TopicName ``` -The topic will show up in the review ``UI`` and in the -``Open Changes List``. Topic branches will disappear from the master -tree when its content is merged. +The topic will show up in the review ``UI`` and in the ``Open Changes List``. +Topic branches will disappear from the master tree when its content is merged. ## Finding Available Topics @@ -81,43 +77,40 @@ tree when its content is merged. $ ssh -p 29418 <LFID>@gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u ``` -- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the current URL where the project is hosted. -- *status* : Indicates the topic's current status: open , merged, - abandoned, draft, merge conflict. -- *project* : Refers to the current name of the project, in this case - fabric. +- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the + current URL where the project is hosted. +- *status* : Indicates the topic's current status: open , merged, abandoned, + draft, merge conflict. +- *project* : Refers to the current name of the project, in this case fabric. - *branch* : The topic is searched at this branch. -- *topic* : The name of an specific topic, leave it blank to include them - all. +- *topic* : The name of an specific topic, leave it blank to include them all. - *sort* : Sorts the found topics, in this case by update (-u). ## Downloading or Checking Out a Change -In the review UI, on the top right corner, the **Download** link -provides a list of commands and hyperlinks to checkout or download diffs -or files. +In the review UI, on the top right corner, the **Download** link provides a list +of commands and hyperlinks to checkout or download diffs or files. -We recommend the use of the *git review* plugin. The steps to install -git review are beyond the scope of this document. Refer to the -[git review documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) +We recommend the use of the *git review* plugin. The steps to install git review +are beyond the scope of this document. Refer to the [git review +documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) for the installation process. -To check out a specific change using Git, the following command usually -works: +To check out a specific change using Git, the following command usually works: ```sh $ git review -d CHANGEID ``` -If you don't have Git-review installed, the following commands will do -the same thing: +If you don't have Git-review installed, the following commands will do the same +thing: ```sh $ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD ``` -For example, for the 4th version of change 2464, NN is the first two -digits (24): +For example, for the 4th version of change 2464, NN is the first two digits +(24): ```sh $ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD @@ -125,8 +118,8 @@ $ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD ## Using Sandbox Branches -You can create your own branches to develop features. The branches are -pushed to the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location. +You can create your own branches to develop features. The branches are pushed to +the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location. These commands ensure the branch is created in Gerrit's server. @@ -157,13 +150,12 @@ $ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME ## Updating the Version of a Change -During the review process, you might be asked to update your change. It -is possible to submit multiple versions of the same change. Each version -of the change is called a patch set. +During the review process, you might be asked to update your change. It is +possible to submit multiple versions of the same change. Each version of the +change is called a patch set. -Always maintain the **Change-Id** that was assigned. For example, there -is a list of commits, **c0...c7**, which were submitted as a topic -branch: +Always maintain the **Change-Id** that was assigned. For example, there is a +list of commits, **c0...c7**, which were submitted as a topic branch: ```sh @@ -176,26 +168,26 @@ $ git log REMOTE/master..master $ git push REMOTE HEAD:refs/for/master/SOMETOPIC ``` -After you get reviewers' feedback, there are changes in **c3** and -**c4** that must be fixed. If the fix requires rebasing, rebasing -changes the commit Ids, see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section for more information. However, you must keep the same Change-Id -and push the changes again: +After you get reviewers' feedback, there are changes in **c3** and **c4** that +must be fixed. If the fix requires rebasing, rebasing changes the commit Ids, +see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section +for more information. However, you must keep the same Change-Id and push the +changes again: ```sh $ git push REMOTE HEAD:refs/for/master/SOMETOPIC ``` -This new push creates a patches revision, your local history is then -cleared. However you can still access the history of your changes in -Gerrit on the ``review UI`` section, for each change. +This new push creates a patches revision, your local history is then cleared. +However you can still access the history of your changes in Gerrit on the +``review UI`` section, for each change. It is also permitted to add more commits when pushing new versions. ### Rebasing -Rebasing is usually the last step before pushing changes to Gerrit; this -allows you to make the necessary *Change-Ids*. The *Change-Ids* must be -kept the same. +Rebasing is usually the last step before pushing changes to Gerrit; this allows +you to make the necessary *Change-Ids*. The *Change-Ids* must be kept the same. - **squash:** mixes two or more commits into a single one. - **reword:** changes the commit message. @@ -208,8 +200,8 @@ kept the same. Before pushing a rebase to your master, ensure that the history has a consecutive order. -For example, your ``REMOTE/master`` has the list of commits from **a0** -to **a4**; Then, your changes **c0...c7** are on top of **a4**; thus: +For example, your ``REMOTE/master`` has the list of commits from **a0** to +**a4**; Then, your changes **c0...c7** are on top of **a4**; thus: ```sh $ git log --oneline REMOTE/master..master @@ -225,8 +217,8 @@ $ git log --oneline REMOTE/master..master c7 ``` -If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull -with a rebase as follows: +If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull with a +rebase as follows: ```sh $ git pull --rebase REMOTE master @@ -247,8 +239,8 @@ c7 ## Getting Better Logs from Git -Use these commands to change the configuration of Git in order to -produce better logs: +Use these commands to change the configuration of Git in order to produce better +logs: ```sh $ git config log.abbrevCommit true @@ -260,12 +252,12 @@ The command above sets the log to abbreviate the commits' hash. $ git config log.abbrev 5 ``` -The command above sets the abbreviation length to the last 5 characters -of the hash. +The command above sets the abbreviation length to the last 5 characters of the +hash. ```sh $ git config format.pretty oneline ``` -The command above avoids the insertion of an unnecessary line before the -Author line. +The command above avoids the insertion of an unnecessary line before the Author +line. |