X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;ds=sidebyside;f=docs%2F07_How_To_Contribute%2F06_Gerrit_Recommended_Practices.md;fp=docs%2F07_How_To_Contribute%2F06_Gerrit_Recommended_Practices.md;h=671c68586f1768419b784d05e0c705ad5892751d;hb=120a2677992ea299eea5fb5cb0ed1081f76bb92c;hp=0000000000000000000000000000000000000000;hpb=33727f4e9619f9da65fdfc608a10a92887c7257c;p=AGL%2Fdocumentation.git diff --git a/docs/07_How_To_Contribute/06_Gerrit_Recommended_Practices.md b/docs/07_How_To_Contribute/06_Gerrit_Recommended_Practices.md new file mode 100644 index 0000000..671c685 --- /dev/null +++ b/docs/07_How_To_Contribute/06_Gerrit_Recommended_Practices.md @@ -0,0 +1,263 @@ +--- +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. + +## 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: + +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. + +```sh +Bug-AGL: SPEC- + +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. + +**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. + +## 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. + +- 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*. + +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: + +```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. + +## Finding Available Topics + +```sh +$ ssh -p 29418 @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. +- *branch* : The topic is searched at this branch. +- *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. + +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: + +```sh +$ git review -d CHANGEID +``` + +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): + +```sh +$ 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. + +These commands ensure the branch is created in Gerrit's server. + +```sh +$ git checkout -b sandbox/USERNAME/BRANCHNAME +$ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME +``` + +Usually, the process to create content is: + +- develop the code, +- break the information into small commits, +- submit changes, +- apply feedback, +- rebase. + +The next command pushes forcibly without review: + +```sh +$ git push REMOTE sandbox/USERNAME/BRANCHNAME +``` + +You can also push forcibly with review: + +```sh +$ 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. + +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 + +$ git log REMOTE/master..master + + c0 + ... + c7 + +$ 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: + +```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. + +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. + +- **squash:** mixes two or more commits into a single one. +- **reword:** changes the commit message. +- **edit:** changes the commit content. +- **reorder:** allows you to interchange the order of the commits. +- **rebase:** stacks the commits on top of the master. + +## Rebasing During a Pull + +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: + +```sh +$ git log --oneline REMOTE/master..master + + a0 + a1 + a2 + a3 + a4 + c0 + c1 + ... + c7 +``` + +If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull with a +rebase as follows: + +```sh +$ git pull --rebase REMOTE master +``` + +This pulls **a5-a7** and re-apply **c0-c7** on top of them: + +```sh +$ git log --oneline REMOTE/master..master +a0 +... +a7 +c0 +c1 +... +c7 +``` + +## Getting Better Logs from Git + +Use these commands to change the configuration of Git in order to produce better +logs: + +```sh +$ git config log.abbrevCommit true +``` + +The command above sets the log to abbreviate the commits' hash. + +```sh +$ git config log.abbrev 5 +``` + +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.