配置管理工具 01 版本控制 gerrit introduction
2016-10-20 14:45
597 查看
Gerrit Introduction
Note, if you are a first time Gerrit user, please take a look at the Setting up Gerrit page.
Contents
[show]
Overview
Main Features
Gerrit is a web-based tool that is used for code review. Its main features are the side-by-side difference viewing and inline commenting, which makes code reviews a quick and simple task.It is used together with the Git version control system. Gerrit allows authorized contributors to merge Changes to the Git repository, after reviews are done. Contributors can get their code reviewed with little effort, and get their Changes quickly through
the system.
Basic Workflow
Gerrit usage has two stages: First, the contributor uploads Changes to Gerrit with Git, and second, peers use the web browser to make reviews. The review process includes the following steps:Review Changes
Publish comments
Approve or abandon Changes
Repository Structure
Gerrit can manage multiple repositories (projects). Branches are fully supported by Gerrit, each repository can have any number of branches.Gerrit stores Changes, which are normal commits, as references in the refs/changes/ namespace. When contributors push Changes, they prepend refs/for/ to
the target branch. For example, when contributor uploads a commit to thedev branch, the target ref will be refs/for/dev.
Terminology
Common terms used in Gerrit:Term | Description |
---|---|
Change | The unit of review. Results in a single commit when merged to the Git repository. Change numbers are unique and never change. |
Patch Set | A revision of a Change. Each time a Change is modified, it will receive a new Patch Set. Patch Set numbering starts from 1. Technically, a Patch Set is a unique Git commit. |
Approval Category | Name for a scope that is checked during review process. Qt is using the categories Code Review and Sanity Review. |
Score | A value in an Approval Category. Indicates if a Change is approved and can be submitted to the Git repository. |
Submit | An action that allows Gerrit to merge a Change to the Git repository. |
Abandon | Action that archives a Change. An abandoned Change can be restored later. |
Project | A Git repository. |
Creating and Uploading Contributions
Preparation
Before any contribution can be created, a Git clone of the target repository must be obtained and properly configured. The necessary steps are explained in Settingup Gerrit.
Creating a New Contribution
All contributions are uploaded with a regular Git push. Gerrit handles reviews at the commit level. A single contribution can easily result in several reviewable Changes in Gerrit. The contributorprepares a contribution by following these steps:
Creating or updating the local repository
Optionally creating a topic branch
Creating commits
Uploading the commit(s) to Gerrit
Soliciting feedback
Creating a topic branch
Keep code organized in topicbranches. This is what Git excels in. "next-big-thing" is used as an example topic branch below:
$ git checkout -b next-big-thing Switched to a new branch 'next-big-thing' $
Creating Commits
See the Git Introduction toget started.
Here are a few notes specific to Qt/Gerrit:
If you correctly set up the clone, the commit message editor will present you with a template for the message.
The guidelines for creating good commit messages - and creating good commits in general, for that matter - are outlined in the Commit
Policy.
On initial creation of a commit, if the commit-msg hook is set up properly, an additional line in the form of "Change-Id: …" should have been added.
Uploading Commits
Changes are pushed to Gerrit with git push. Note that a special target ref is used. Gerrit reports how many Changes were created and provideslinks to these Changes.
$ git push gerrit HEAD:refs/for/dev Counting objects: 6, done. Delta compression using up to 2 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (4/4), 407 bytes, done. Total 4 (delta 2), reused 0 (delta 0) remote: Resolving deltas: 100% (2/2) remote: Processing changes: new: 1, refs: 1, done remote: remote: New Changes: remote: https://codereview.qt-project.org/12345 remote: To ssh://qtcontributor@codereview.qt-project.org:29418/qt/qtbase * [new branch] HEAD -> refs/for/dev $
When pushing to Gerrit, a typical refspec uses
HEAD as the source ref and a special Gerrit ref for the target branch. The target ref has the format refs/for/<branch name>. Pushes to this target ref causes Gerrit to create new Changes for all commits pushed
this way. To group your Changes, push to a topic by using the format refs/for/<branch
name>/<topic name>. Note that it is possible to use any other ref as source ref instead of HEAD when necessary. See Branch
Guidelines to decide about the target branch.
It is recommended that you use the git-gpush command from our qtrepotools
repository (make sure to add the bin directory to your PATH for maximal convenience):
$ git gpush [same output as above]
Once a Change has been created, it can be viewed in the web browser:
Soliciting Feedback
The contributor requests feedback by adding reviewers to the Change. This is typically done via the web browser. Access the Change with the web browser and use the "Add Reviewer" button toadd any other registered user(s) to the review.
Alternatively, reviewers can be added already when uploading a contribution. Use the git-gpush tool for that purpose:
$ git gpush +approver@example.com [same output as above]
Review Workflow
It is easy to get an overview of pending contributions in the "My Changes" page, also known as the "Dashboard":It is possible to find Changes by issuing search
queries. Links for the Change owner, project name and branch name in the search result listings can be used to quickly search for related Changes.
The navigation bar at the top of the Gerrit web view provides quick access to common search queries under the "My" and "All" items.
Reviewing Contributions
The review process starts with choosing a Change to review. After choosing a Change, changed files can be viewed side-by-side and comments can be posted in-line to each file. Contributionsare typically reviewed by Approvers, but anyone can make a review.
The following steps are needed to complete a code review:
Opening the Change page (entered from the Dashboard or following a link in a notification mail)
Reviewing changed files
Publishing comments and reviewing results
Viewing the Change Overview
Changes can have several Patch Sets. When Changes get updated after review, the Patch Set number increases.
Reviewing Changed Files
Changes are compared side-by-side or in the unified diff view. The reviewer can also compare differences between specific Patch Sets (also called "inter-diffs").Comments are posted by double clicking on a line. Comments are saved as drafts until they are published as in the pictures:
Gerrit keeps track which files have been reviewed and which files have comments ready to be published. If an ongoing review is interrupted, the reviewer can return later and resume where
they left off. Draft comments can be edited and deleted before they are published.
Downloading Changes
It is also possible to download Changes for local review. The easiest way to do that is to copy the Download link from Gerrit to the command line:
$ git fetch ssh://qtcontributor@codereview.qt-project.org:29418/qt/qtbase refs/changes/19/419/1 && git checkout FETCH_HEAD From ssh://codereview.qt-project.org:29418/qt/qtbase * branch refs/changes/19/419/1 -> FETCH_HEAD Note: checking out 'FETCH_HEAD'. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by performing another checkout. If you want to create a new branch to retain commits you create, you may do so (now or later) by using -b with the checkout command again. Example: git checkout -b new_branch_name HEAD is now at 9a006a3... My Feature $ git checkout -b changes/419 Switched to a new branch 'changes/419' $
This makes it possible to use the usual git commands to view changes, to build the code, and to run tests.
Publishing Comments
When all files are reviewed, the reviewer continues to the Publish Comments screen with the Review button.The review is completed by writing an optional cover message and giving a score.
The Code Review category has 5 levels. A Change can only be submitted after it receives a +2 score, and cannot be be submitted if it receives a -2 score. Giving these scores is limited to
Approvers; regular contributors can give only advisory scores (-1 to +1).
A Sanity Review score should not be given unless the Sanity
Bot made a mistake and needs to be overridden.
Publishing Review Results From The Command Line
An alternative to browser-based review is to use the Gerrit ssh command line interface. Please do not do this, as scripting a step which is meant to be visual and interactive removes
the additional safety net.
Processing Review Feedback
The contributor can view feedback on their contributions by accessing the Change page and reading comments file-by-file. It is possible to reply to comments and have a discussion about thecode review in-line.
The contributor processes the feedback by following these steps:
Opening the Change page (entered from the Dashboard or following a link in a notification mail)
Locating comments in the Change page
Reading and writing in-line comments
Publishing a reply and/or uploading a new Patch Set
Locating Comments in The Change
Comments are located below the list of Patch Sets. In the picture below the comments for Patch Set 2 are examined:
Reading in-line Comments
Replies can be posted by clicking the comment like in the picture below:Note that the comments are not actually posted until you publish them.
Note: do not reply to the notification mails you get from Gerrit. The mails you send this way will not be publicly visible and archived.
Updating a Contribution With New Code
Most Changes require multiple iterations of the review process. The contributor needs to update the Change if it received some comments that require action, or it did not merge with the branchtip. Each time a Change is updated, it gains a new Patch Set.
Updating a Change is done by following these steps:
Accessing the Changes
Modifying the Change(s)
Pushing updated Changes
Accessing The Changes
If the original commit(s) are still available, it is possible to amend them right away. Otherwise, download the Change(s) the same way as for local review.If Gerrit reported a merge conflict, now would be the time to rebase the Changes:
$ git rebase --onto origin/dev
If you are not using a separate branch, you can just use git pull --rebase.
Note: Please do not rebase unnecessarily, as this makes inter-diffs much less useful.
Modifying Commits
Modifications in the working tree are committed with the --amend option. If the contribution consists of multiple commits, you will need to use gitrebase --interactive to revise earlier commits.
When you amend commit messages, make sure to preserve the Change-Id footer, as this is how Gerrit identifies new Patch Sets for existing Changes.
$ vim src/foo.cc $ git add src/foo.cc $ git commit --amend [changes/419 2ea7773] My Feature 1 files changed, 1 insertions(+), 0 deletions(-) create mode 100644 src/foo.cc $
Pay even more attention to copying the Change-Id when you redo commits from scratch.
Pushing Updated Changes
The commit(s) are uploaded back to Gerrit with the same target ref as before. After the push, new Patch Sets will have been created for the target Change(s):$ git push gerrit HEAD:refs/for/dev Counting objects: 6, done. Delta compression using up to 2 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (4/4), 419 bytes, done. Total 4 (delta 2), reused 0 (delta 0) remote: Resolving deltas: 100% (2/2) remote: Processing changes: updated: 1, refs: 1, done To ssh://qtcontributor@codereview.qt-project.org:29418/qt/qtbase.git * [new branch] HEAD -> refs/for/dev $
Integrating Changes
There are two ways to submit a Change. If the project is using a continuous integration system, Changes will be merged to staging. Otherwise, they will be submitted directly to their destinationbranch.
To submit a Change to the CI system press "Merge Patch Set <n> to Staging".
To submit a Change directly to the target branch press "Submit Patch Set <n>"
It is usually best when the contributor submits their own Changes.
Even if there are multiple reviewers, only one +2 approval is required. However, if other reviewers have shown a specific interest in a contribution, such as by repeated comments, it is polite
to give them some time to add a +1 or +2 before submitting.
Continuous Integration
Gerrit has been slightly customized for the Qt project. The continuous integration system that is running regular builds and tests has been incorporated to the workflow. Instead of directlysubmitting Changes, Changes can be merged to a staging branch. There is a staging branch for each normal branch. Staging branches are maintained by Gerrit and are not visible to the contributors.
As part of the customization, Changes gained new states. Changes in the New state are waiting for a review. After review, Changes are merged to a staging branch and marked as Staged. The
continuous integration system will pick staged Changes at regular intervals and move them to the Integrating state. From the Integrating state Changes are either submitted or moved back to the New state. If builds succeed and tests pass, the Changes are submitted
or merged into their destination branch. Otherwise they are moved back to the New state for further analysis. The contributor of the affected Change(s) is expected to analyze the failure and upload fixes as necessary.
Abandoning and Deferring Contributions
Changes which are inherently flawed or became inapplicable should be abandoned. An abandoned Change will disappear from open Changes lists and is considered closed. Abandoned Changes canbe restored later if they become valid again or if they were abandoned by accident.
Changes which have potential but will not be worked on in the near future should be deferred. Deferred Changes are basically abandoned, but are more easily accessible via the "My Deferred
Changes" menu item.
Abandoning is a normal operation that is used to maintain Gerrit and hide Changes that will not make their way to the Git repository, for any reason.
To abandon a Change, its owner or an Administrator can click the "Abandon Change" button:
Feature Branches
The Qt Project's handling of branches is documented by the BranchGuidelines.
Topics vs. Branches
Gerrit topics can be used as "feature branches". A topic is created when a target ref like refs/for/<branch name>/<topic name> is used. It isoften good enough to push a set of commits for review to a topic. However, if the contributor intends to work with others on a long-living branch, the Gerrit Administrators should be contacted for a new branch in Gerrit. Also, the QA team has to be contacted
so they can include the new branch in the CI system builds. This way the code can be reviewed already when working on it in the branch.
Merging Feature Branches
Merges between feature branches and the mainline are like all other commits and are pushed, reviewed and staged the usual way. However, only 'Merge Masters' can push merge commits. User mayrecruit the merge master from outside project team if it they do not have person knowledgeable on Git available. Note: Do not create a merge from commits which have not been integrated yet.
Merging Branches Alien to Gerrit
This should not happen often. Nevertheless, only a merge commit should be pushed in this case. 'Push Master' can be asked to import the branch into Gerrit.
Closing Remarks
See Gerrit Caveatsand Hints to avoid common traps.
There is a process for requesting
new repositories.
Report bugs in our Gerrit to the
bugtracker. Ideally, provide a link to an upstream issue (note that the
issue may be already closed, as we are typically lagging by several versions).
Category:
Developing Qt
Navigation menu
Signin
Page
Discussion
Read
View
source
View
history
Main page
Recent changes
Random page
Help
Tools
What links hereRelated changes
Special pages
Printable version
Permanent link
Page information
This page was last modified on 1 July 2016, at 16:56.
This page has been accessed 37,798 times.
REF:
https://wiki.qt.io/Gerrit_Introduction
相关文章推荐
- 版本控制配置工具杂谈(不断更新中)
- MYPM 国产非开源免费测试管理工具软件 WEB2.0用户体验零配置安装版本发布
- msysgit + TortoiseGit:在 windows 上安装配置版本控制工具 Git 图形化使用
- git中关于文件是否加进版本控制管理库中的.gitignore文件配置
- 项目管理/版本控制工具
- RT-Thread 学习笔记(二)---配置github代码版本控制工具
- 版本控制(九)--git创建&服务器&配置&工具
- 配置管理论文_产品版本控制实践 [ 光影人像 东海陈光剑 的博客 ]
- 版本控制工具安装与配置
- (转载)【版本控制工具】svn服务器、客户端安装配置
- 项目管理实践之版本控制工具SVN在Windows平台下的平台搭建
- 【版本控制工具】svn服务器、客户端安装配置及eclipse的svn检出
- 版本控制管理工具--git的学习记录
- 【版本控制工具】svn服务器、客户端安装配置及eclipse的svn检出 推荐
- 配置管理之版本管理工具
- 配置管理--版本控制的目的
- 项目管理实践之版本控制工具SVN
- 数据库迁移、版本控制管理工具-Flyway
- 关于测试方面一些版本控制及管理工具的安装及使用
- 用SVN进行版本控制和项目管理的安装配置和使用方法