How to Modify Label on Gerrit Using Gerrit Review

Gerrit tutorial. This tutorial explains the installation and usage of the Gerrit code review system. It describes the setup of Eclipse (with EGit) besides as the command line setup.

1. Code review

1.i. The code review process

A code review procedure is based on a process in which people tin can suggest, review, update and accept changes.

Once a alter is accepted, people with the correct permission can accept it.

The involved people are typically decided into two groups: * contributors - people with the permission to create, review and update changes * committers - people with the additional permission to accept changes

A lawmaking review process can be implemented without any tool back up. But it is typically more efficient, if a structured code review system is used.

Using a code review system, allows to perform an automated test build of the proposed merge. Continuous integration tools like Jenkins or Hudson tin integrate with the review organization to find compile errors and to run a test suite.

In general a structured lawmaking review process has the following advantages:

• Early on mistake detection:

  • Build bug are detected immediately past automated test builds.

  • Logical flaws can be spotted by the man reviewer before any code is merged.

• Alignment with project standards:

  • Allows the team to place early in the procedure any violations with the team lawmaking standards.

  • Helps to continue code readable and easier to maintain.

  • Allows continuous integration system also checks for code standard conformity automatically as part of the build process.

• Knowledge exchange:

  • The lawmaking review procedure allows newcomers to see the code of other more experienced developers.

  • Developers can go feedback on their suggested changes.

  • Experienced developers can assist to evaluate the impact on the whole code.

  • Shared code ownership: by reviewing code of other developers the whole team gets a solid knowledge of the consummate lawmaking base.

• Easy entry to contribution: People without write permission to a repository have an easy way to offset contributing and to get feedback.

• Enables review before a alter is submitted: Iteration based on review comments / build results happen before a change is merged into the target branch. This result in a cleaner history of the repository.

For an efficient process, the code review should be conducted in a supportive environment where constructive feedback is given to enhance the change.

1.2. The Gerrit code review system?

Gerrit is a code review arrangement developed for the Git version command arrangement. It is a web based lawmaking review organization, facilitating online code reviews for projects. Gerrit is a Git server which adds a fine grained access command system and a lawmaking review system and workflow.

The user interface of Gerrit is based on Google Spider web Toolkit. Its uses JGit library to provide the Git functionality.

A developer can utilize Gerrit to suggest a change. Other developers can review the change and suggest improvements. If a Gerrit change needs improvement, it is possible to update it with a new commit. Once the suggested changes are accepted, they can be merged to the target branch of the Git repository via the Gerrit user interface.

Gerrit makes code reviews easier by showing changes in a side-by-side display. It too supports to display the modify as a unified diff which is often easier to read on smaller screens.

A reviewer can add together comments to every single line changed.

Gerrit is licensed nether the Apache 2.0 license.

The Gerrit review organization uses the term change, to define a lawmaking review / review asking. Each alter is based on ane commit.

ane.three. How does Gerrit piece of work?

Gerrit tin prevent users from pushing direct to the Git repository. If you push to Gerrit, you apply a certain path ( ref specification) which tells Gerrit that you want to create a change. This push button ref specification is refs/for/master if the target of the alter under review is the master branch. Y'all can also push to refs/for/xyz to put a commit into the review queue for the xyz branch.

If y'all push to this ref specification, Gerrit creates a new alter or makes an update of an existing i. Gerrit uses the Change-Id information in the commit bulletin to place if the push is a new commit or an update of an existing modify.

A change consists of one or more patch sets which are used to ameliorate the first proposal based on review comments. I patch prepare corresponds to one Git commit.

Information technology is still possible to bypass lawmaking review past pushing directly to refs/heads/master if sufficient rights have been granted.

1.4. Review categories - Verified and Code-Review

Gerrit supports different categories (too known as labels) for review feedback. In its default configuration it supports the Code-Review category.

In typical installations also the Verified category is installed.

The Verified category typically means you were able to build and test the change introduced with the Gerrit alter. Typically, this is done past an automated process such every bit a Jenkins / Hudson build server.

The "Code-Review" category is typically used to vote on the quality of the implementation, lawmaking style, code conformity. It also indicates that the modify is in accordance with the standards desired past the project.

Committers and contributors tin can vote in these categories.

1.v. Voting in Gerrit

The rules for voting in Gerrit is:

• Highest vote (+2 in Code-Review and +1 in Verified) enables submitting

• Lowest vote (-2 in Code-Review) is a veto blocking that the change can exist submitted and tin't be overruled by other reviewers

• You cannot submit the changes to the Git repository until there is the highest vote in all categories

Typically Gerrit instances uses the Verified and the Code-Review category.

If you did some manual testing and the code works as yous desire then it is expert to +i in the "Verified" category. Or give -1 if it failed some of your use cases that must be resolved in order to merge. Otherwise, exit it every bit 0, if you did not test the code.

Non-committers of the project can vote with -i and +i to betoken an opinion in either way. But ultimately information technology is up to the decision of those with +2 power to make the overall decision. You may want to -two vote to block the submission of the code. Or vote +two to bespeak that yous approve that the contribution is merged into the Git repository.

i.half-dozen. Posting draft reviews

There is as well a special refs/drafts/chief refspec which you can use to push changes to for individual review before publishing them to all developers.

This is useful if your work is in progress and not ready for public reviews. You lot can also CC specific people to review this private change. Once it is fix for public review there is a Publish push button to convert the draft into a modify review.

2. Installation of Gerrit

The installation of Gerrit tin exist done direct on a server or within a Docker container.

2.1. Installation of Gerrit on a server

A server can likewise be the local machine, for example, if you desire to test Gerrit.

2.1.1. Download Gerrit

The download is a .war file. This war file tin run in a servlet container, for case, a Jetty or Tomcat installation. The .war file contains a Jetty spider web server and can be started direct for testing or rapid deployment.

The following description uses the approach to showtime the Gerrit server direct via the command line.

2.1.2. Setup of Gerrit

Copy the .state of war file into an empty directory.

Switch on the command line to the location of the directory to which you extracted the .war file. Install Gerrit with the following command.

                                          #                                            create Gerrit review site with questionaire                      java -jar gerrit*.war init -d review_site                                            #                                            alternatively utilize the                      --batch                      command                      java -jar gerrit*.war init --batch -d review_site                                      

If Coffee does not find the jar if yous use *, utilize the full name. This is for example required on Microsoft windows.

The Gerrit example is installed into the folder specified with the -d parameter, in this example review_site.

If you do not use --batch flag, you can interactively configure the Gerrit instance via a set of questions. A few of these options are discussed in the following table.

Table 1. Gerrit setup options

Selection	Clarification
Location of Git repositories	Location of Git repositories, default is the git directory in the installation folder of your Gerrit installation.
Database server type	Gerrit supports several databases, past default it uses a preconfigured H2 database.
Run every bit user	Select that Gerrits runs as "root" user.
Listen on port	Allows you to configure the port Gerrit is listening to, Gerrit by default listens on port 29418 for SSH access and on port 8080 for web access. This can be changed if the ports are already used.
Authentication method	Typical configuring to access the Gerrit server uses LDAP or OpenID Single Sign-on which is the default setting. Use ? to see all available settings for this option. For testing employ "development_become_any_account".

Use development_become_any_account to enable general access to Gerrit. If started with this setting, yous take a Go link in the web interface which allows y'all to login and to create a new account. To enable that authentication method, you can utilize the post-obit command: git config --file ~/etc/gerrit.config auth.type DEVELOPMENT_BECOME_ANY_ACCOUNT

two.1.3. Start Gerrit server

After a successful installation Gerrit starts automatically on Unix-similar systems. Y'all can start and end information technology once more with the following commands on Linux based systems.

                                          #                                            assumes you installed Gerrit                      in                      #                                            the home directory under gerrit                                                                  #                                            start                      if                      not running                      ~/gerrit/review_site/bin/gerrit.sh outset                                            #                                            stop it again                      ~/gerrit/review_site/bin/gerrit.sh stop                                      

On Microsoft Windows based systems you demand to invoke the daemon directly. If you created your Gerrit installation in the binder review_site, start your Gerrit server via the following control.

                                          java                      -jar                                            review_site                      /bin/gerrit.war                      daemon                      -d                      .                  

This starts Gerrit. To stop it again, kill the running procedure using Ctrl+C .

If something goes incorrect, wait into the logs folder.

The local Gerrit configuration is stored in the ./review_site/etc/ folder.

3. Gerrit workflow

3.i. A typical Gerrit workflow

The following describes a typical Gerrit workflow of you as a developer using Gerrit.

• You lot fetch or pull in the latest changes from the Git repository

• Optionally, you lot create a new local branch based on the origin/principal co-operative.

This step is optional simply it is considered a skilful practice to create an independent branch per change to avoid unnecessary dependencies between commits (Gerrit reviews).

• You implement a alter (new feature, bug fix, documentation modify) and create a commit in his local repository with these modifications.

• implements (if necessary) more changes and amends the existing commit, until he is satisfied with the change.

Afterwards y'all perform the following steps.

• Push button the change to the Gerrit review system to the refs/for/master refspec to create a alter for the master branch.

• If y'all receive improvement suggestions, fetch the latest changes and rebase your patch onto origin/master

Repeat the last three steps until the patch is finally accepted and merged into the codebase (or until the change is completely rejected). Finally yous can delete your local co-operative.

3.2. Gerrit vs. Git workflow

In the Gerrit scenario alteration a commit is used to update the Gerrit change request. Using the meliorate operation on a published commit is usually discouraged in Git, in Gerrit it is the normal procedure.

three.3. Gerrit vs. GitHub workflow

The Gerrit review arrangement is based on the assumption that each commit is reviewed separately. At GitHub, a complete branch is reviewed and merging with the pull request.

four. User setup

4.1. Create user

You require a valid Gerrit user to work with Gerrit. In your test installation, you create your ain users.

If you are not the administrator, you lot accept to ask the responsible person to create a user for you lot.

Login to your Gerrit installation. Assuming that you lot installed information technology on your local machine using the default values, you lot can access it via the post-obit URL:

http://localhost:8080/login/

The get-go user to login automatically gets the administrator condition.

4.2. SSH setup

If you want to utilize SSH you accept to upload your SSH key. If you lot prefer to apply HTTPS, skip this step and go to HTTPS setup.

From the user drop down menu select Settings and select SSH Keys to upload your public SSH cardinal.

Based on your SSH key y'all are now able to substitution information with the Gerrit server.

Select Profile to assign a Username to your user.

4.3. HTTPS setup

You can as well enter a password for HTTPS admission.

5. Ambassador: Upload Git repository

This role is simply relevant for the administrator. Create a new Git repository chosen gerrittest via EGit or the Git command line.

Create a the new Git repository in Gerrit via the following command.

                # assumes that Gerrit runs on port 29418 # on localhost  ssh -p 29418 <userid>@localhost gerrit create-project demo/gerrittest              

You can also click in the web interface.

The new project tin can be found in the Gerrit web interface under .

Select your project and . For testing give push rights to all registered users, which is the default afterwards a fresh installation. In a productive environs, you can configure Gerrit to be more restrictive. Specially the access right Push button Merge Commit for characteristic branches named refs/heads/* is something simply trusted and experienced committers should be allowed to do.

half-dozen. Ambassador: Create instance project

Also for testing create a new Java project called com.vogella.gerrit.case. Add a few classes to it. Create a new local Git repository and add the projection to information technology.

Afterwards push the local Git repository to Gerrit by selecting . Enter the following URL ssh://<userid>@localhost:29418/demo/gerrittest.git in the sorcerer and press the Next button.

On the next page, click the Add All Branches Spec button.

Press the Adjacent button and on the last wizard page the Finish button.

This pushes the changes directly to the Git repository without a change in Gerrit. This is possible as the default permissions in Gerrit are set to allow this.

seven. Project Owner: Editing the project config through Git

Each Gerrit project is configured via a project configuration file. Yous tin edit the project configuration via the webuser interface, under .

It is possible to edit this directly. The config files are store in the projects Git repository. They reside in the special branch refs/meta/config. To check them out issue the post-obit commands on your terminal:

                                  git remote add together gerrit ssh://<gerrit-site>:<gerrit-port>                  git fetch gerrit refs/meta/config:refs/remotes/gerrithub/meta/config git checkout gerrithub/meta/config                              

Your project specific rules are in the file project.config. The file follows the Git configuration format.

Assuming your project is lacking the "Verified" label you could add the following to the config:

                [label "Verified"]        office = MaxWithBlock        value = -1 Fails        value =  0 No score        value = +i Verified              

After you take commited your changes you lot can button them:

                                  git push -f gerrithub  HEAD:refs/meta/config                              

eight. Project Possessor: Managing project admission

Project access in Gerrit is by and large handled through Groups, although yous tin besides fix permissions on a per user basis. An open source project might have a group for commiters, who can review and merge changes, and a group for their CI solutions. To create a new group navigate to .

Once you have created a group you are taken to the group management page, where yous can add new members to the grouping.

After that yous can give this Group access to your project. This is done either through the web interface at or past editing the projects config file as described in Project Possessor: Editing the projection config through Git.

9. Developer: Clone repository from Gerrit

In this practice y'all act as a programmer who wants to upload a Gerrit review. This requires that yous have a valid Gerrit user on the Gerrit system.

For this practise, it is causeless that you lot have non notwithstanding a local Git repository. Therefore, y'all demand to clone the Git repository from the Gerrit server. Apply a new workspace for this.

Open the Git Repositories view in Eclipse and select that you want to clone an existing repository. Enter the URL from the Git repository hosted at Gerrit, for example: ssh://<user-id>@localhost:29418/demo/gerrittest.git.

10. Programmer: Gerrit configuration for the Git repository

If you lot used Eclipse for cloning the Git repository from Gerrit, you can skip this footstep. Eclipse configured itself automatically to work with Gerrit. If you cloned via the command line, you need to perform this configuration pace.

Right-click on your cloned repository in the Git Repositories view on the origin remote and select Gerrit Configuration…​.

The default values in this dialog are okay. Press the Terminate button.

This sets your push configuration for this remote to refs/for/* which tells Gerrit that you lot created or updated a change. To valid the push configuration, right-click on your remote and select Configure push button. Ensure that the setting is similar to the following screenshot. It too adds a flag to your repository to tell the Eclipse Git tooling to create a Gerrit Change-id.

Use the Backdrop view on your repository to see the details of your repository configuration.

The refs/for/* ensures that every button is handled past Gerrit. If you use the refs/heads/master ref mapping, you can directly push to the Git repository. This selection is typically restricted to administrators.

You tin also practice this setup directly via the Git command line.

                git config remote.origin.push button refs/heads/*:refs/for/*              

xi. Creating and updating a Gerrit change request from Eclipse

In the post-obit description nosotros create a Gerrit modify request.

Later getting the latest source lawmaking, when y'all are ready for development, create a new local branch starting from the origin/primary branch.

Perform some changes in your Coffee projection. Commit the changes and ensure to select the Add Modify-Id push button in the Git Staging view.

The Alter-ID is what uniquely identifies the change in Gerrit. The entry is initially set to Modify-Id: I0000000000000000000000000000000000000000. During the commit, this is replaced with an ID generated by the Git tooling.

Push button the modify to Gerrit. As your button configuration is configured for Gerrit, this should create a modify. The Eclipse Git tooling shows a dialog later the push. This dialog contains error messages in example the push was not successful. Via the URL you can access the Gerrit web interface and analyze the Gerrit review.

Do a few new changes to your Coffee project and commit them to your local Git repository. Ensure that you lot improve the existing commit. This makes certain the existing change id is used and avoids that Gerrit cannot apply your modify because of a dependency cycle on the commits. Push your new commit to Gerrit, this should update the existing review request. The Eclipse Git push button confirmation dialog should tell yous that you lot created a new modify set.

12. Combining changes from two commits / Gerrit change reviews

Sometimes you want to update an existing Gerrit but push a new commit which creates a new Gerrit. So yous have two Gerrit change reviews, instead of ane.

Hither is what you accept to practise to combine them:

• Use Ctrl+three Fetch from Gerrit and fetch the second Gerrit into your local repository

• Get to the history view, you will see both commits

• Select the last commit before the ii commits which you lot want to combine

• Correct-mouse clicke and select Rebase Interactive

• In the Rebase view, select Fixup on the 2nd commit to combine two commits using the commit message from the first commit.

• Printing Kickoff to run the interactive rebase

• Push the changed commit to Gerrit, this will update the offset Gerrit, equally the Change-Id is still the same.

• Abandon the second commit

13. URL for reviews

To see the reviews on your Gerrit server, open the link to your Gerrit instance. For example if you accept Gerrit locally installed use

which is the default port for a local Gerrit installation. Yous run across all change requests, if yous login into the Gerrit instance yous encounter Gerrit changes y'all are involved with.

14. Using the Gerrit web interface

14.1. Reviewing a change request

Click on ane modify request to see the details of the Gerrit modify request. Click on the commit message of the file name (highlighted in the screenshot) to see the changes in the file.

You can double-click on a line to annotate on the change.

Clicking on Upward to change brings you back to the change.

Gerrit allows you to review the commit message, which appears at the top of the file listing. To sympathize the history of the repository it is important to provide a good commit message.

14.2. Publishing your review event

Click on Reply push to give feedback on the modify.

You can requite a summary of your feedback and render a review number betwixt -2 and +2 (if you are a committer) or betwixt -1 and +1 (if you are not a committer). If yous vote -one or -2, y'all respectively bespeak that the patch still requires rework or that you disagree with the suggested change. Run across Voting in Gerrit for details of the default voting rules.

14.3. Ameliorate a change based on review feedback

If the review procedure has resulted review comments explaining how to improve the proposed patch, the author of the patch (or someone else) can adjust the patch. The developer amends the commit in his local repository and pushes the improved commit to Gerrit. He tin can likewise conform the commit message while amending the commit.

As the developer apology the commit, the same Change-Id is used and the Gerrit review system identifies the change every bit update of the existing change.

The Git Staging view allows amending the terminal commit by clicking the better push button shown in the screenshot.

Gerrit allows you to select which patch sets you want to compare in Comparison view. Typically you compare the base of operations version with the latest patch set, but if eastward.one thousand. you already reviewed patch set 3 you may want to just see what the author changed between patchset 3 and patchset five.

In one case the change has reached the required quality, the reviewer tin can give a +two evaluation of the change.

Depending on the settings of the Gerrit repository, the Gerrit review might take to be rebased. If conflicts happen during this rebase operation, you can trigger this rebase direct from the web interface. If a change is rebased, it needs to be reviewed again.

Afterwards a developer with commit rights can submit the change. This is typically done by the same committer who voted +2. This may crave that the corresponding commit is based on the electric current origin/master co-operative. This depends on the Gerrit configuration for the project. The Gerrit UI allows the committer or contributor to rebase the change onto origin/master if no conflicts occur.

fourteen.four. Keyboard shortcuts in Gerrit

Press the "?" key in the Gerrit web user interface to see the actions you can trigger via shortcuts. The available shortcuts depend on there you lot are in the user interface.

The bachelor shortcuts are different, depending on the page your are.

xiv.5. Fetching a remote change into a local Git repository

It is possible to fetch the changes from the Gerrit review into some other local Git repository. The Gerrit page lists the commands for downloading the modify. This is depicted in the following screenshot.

After fetching a change, the developer can conform the alter and improve the commit. If he pushes information technology to Gerrit, the alter is updated. Such a procedure should be coordinated past the writer of the original change to avert that ii developers exercise the same piece of work.

14.6. Fetching a remote change with Eclipse Git

The Git tooling in Eclipse allows you to fetch a alter from Gerrit. For this, right-click on the projection .

When working with many projects, information technology is often easier to correct-click on the repository instead and access Fetch from Gerrit from in that location. You can paste the alter's number (shown in the change'due south URL) and use Ctrl+Infinite to expand the change number to the list of patch sets. Select the one you lot want to download and fetch it into a new local co-operative. Afterwards you lot tin examination the changes in isolation.

14.7. Edit a alter straight via the web interface

Yous can also edit directly in Gerrit. Press the edit button for this.

Afterwards select the file or the commit message you want to edit. Press save and close once you are done. Subsequently you are done with all your edits, printing the Publish Edit.

fifteen. Solving typical Gerrit problems

xv.1. You forgot to amend the commit

If you endeavor to push a commit which contains the same ChangeId equally a predecessor commit, Gerrit rejects it and responds with the error message: "squash commits offset".

In this example you probably forgot to amend the existing commit and used the aforementioned Gerrit Change-ID. This is depicted in the following graphic.

In this case you need to squash the commits. This results in a new commit which tin be pushed to Gerrit. As you use the same Modify-ID this pushed commit updates the Gerrit review. In the following diagram the "Commit 2'" is the issue of squashing "Commit 2" and "Commit iii" into one commit.

An easy solution to handle this is, to exercise a soft reset in Git to the previous commit and commit the change files once more, this fourth dimension with the amend pick. If you really intended to create 2 commits you need to generate a new changeId in the second commit which was rejected.

The Git tooling in Eclipse allows squashing commits via the Git Interactive Rebase view. A simple way of doing this is by selecting the side by side commits yous want to squash in the History view and by selecting from the context menu.

15.2. Handling merge conflicts

The submit step may fail due to merge conflicts, depending on the Gerrit project configuration.

The easiest fashion to do so is via the Rebase push in the Gerrit web interface, if in that location are no conflicts.

In case you accept to resolve merge conflicts y'all take to do this locally and push an updated commit. The steps required to solve a merge disharmonize are:

• Rebase your local branch onto the latest state of origin/master

• Resolve all conflicts

• Commit them using

• Push your change once more to Gerrit for review

This creates a new patch prepare for the alter. The new patch set has to pass the code review once more. Submit the new patch set up modify to merge it into the master branch.

fifteen.3. non-fast frontwards

Y'all get this error message, if you lot endeavor to submit a commit which would result in a non-fast forward merge. The Gerrit service is sometimes configured with the setting to let only fast-forward merges.

The default submit type in Gerrit is "Merge if necessary".

In this example the pushed commit is non based on the current tip of the remote co-operative. This problem is depicted in the following graphic.

The solution is to rebase your commit onto origin/master. Afterwards yous push the commit once more to Gerrit.

xvi. More infos on trouble shooting

sixteen.1. Remove a bad commit from a series of commits

If you create a series of dependent commits, it might happen that one of the commits is rejected during the review procedure.

In this example, you cannot merge the other commits every bit they all the same accept a dependency to the "bad" commit.

During the review procedure commit 2 are rejected. The commit 3 and commit 4 are however practiced and do not depend on the changes in commit 2.

The solution is to use interactive rebase to skip the bad commit.

The Gerrit user interface does prove "depends on" and "needed by" fields when information technology knows that a Gerrit review depends on another review. This helps you manage your dependency trail.

17. Things to consider if you want to contribute to an existing projection

17.i. How to first contributing?

It is typically a practiced approach to set up something really simple as the start pace. Search for a few alert letters in the code, or a typo in the documentation, and prepare a ready for it.

Once you get familiar with the contribution process commencement contributing something more difficult.

17.2. Scope of a Gerrit alter / commit

A Gerrit change (== 1 commit) should address simply one effect.

Avoid going "off topic" with your patches. If you would like to clean up some lawmaking, or fix something out of the telescopic of your patch, create additional patches. This will make your patches more curtailed, easier to review and easier to revert if something go wrong.

In many open source projects smaller patches tend to exist reviewed faster and merged faster as information technology is easier for the committer to review. With this in mind, try to suspension your contributions into small concise Gerrit changes. It is more likely that these get reviewed and accustomed.

Information technology also helps to achieve a clean history. Imagine yous are chasing a bug in code which was introduced two years back. If the history is built from pocket-sized concise commits, it is easier to find the commit which introduced the problem and empathise the motivation why it was done in the style it was implemented.

17.3. Commit bulletin

Most projection handles the required commit message a bit differently. For example, the Eclipse Platform project prefers the following format:

                                      Bug                    XXXXXXXX                    -                    bug                    championship                    Short                    description                    of                    what                    the                    fix                    contains                    ,                    or                    the                    management                    of                    the                    fix                    Change                    -                    Id:                    I0000000000000000000000000000000000000000                    Signed                    -                    off                    -                    by:                    electronic mail                    -                    from                    -                    the                    -                    CLA                                  

The text in the header must match the championship in Bugzilla. The Eclipse Git tooling complains well-nigh commit headers longer than 80, but you can ignore this warning. For example the following is a valid commit message for the Eclipse platform project. The description in the body of the commit message can take equally many lines as necessary and should be descriptive of what is going into the patch. For more complex patches yous should provide implementation details and enough notes to permit the reviewer to understand what your fix provides.

                  Problems 434846 - Update the organization default Locale if the -nl Locale is invalid  An wrong locale value causes the IEclipseContext to run the conversion often. The patch ensures that but valid values are saved in Eclipse context.  Alter-Id: I6099172a5986e9678a830f84d78b2cdb8c161dc6 Signed-off-by: Dirk Fauth <dirk.fauth@faux.com>                

It is of import to explain in the commit body, why the change was done. Besides explain why you lot have chosen a certain implementation method, if there was something special near information technology.

Don't worry as well much about the correct commit bulletin format, the project you lot are contributing to will also review your commit message.

In some projects the source file contains a copyright header. If you modify the file you should besides update the copyright header. Unlike projection might use different standards here. Accept a await at existing commits and the header in the existing files and try to adapt the fashion preferred by the existing developers.

Almost Eclipse projects to not required to update the copyright header. Optionally you can also add yourself to the copyright with a reference to the problems and update the copyright header with the terminal modified year. The following listing shows an example for this standard.

                  /******************************************************************************* * Copyright (c) 2008, 2015 IBM Corporation and others. * All rights reserved. This plan and the accompanying materials * are made available nether the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at * http://world wide web.eclipse.org/legal/epl-v10.html * * Contributors: *     IBM Corporation - initial API and implementation *     John Doe <John.Doe@fake.org> - Bug 429728 Set compiler alert *******************************************************************************/                

The above file was created in 2008 and last modified in 2015. It was originally created by employees of IBM and too modified by John Doe and he fixed Problems 429728 with it. The additional entry in the Contributors department is typically considered optional, but this depends on the private projection.

If you piece of work for an organization the Foundation recommends adding the organisation name in parentheses. See: Copyright info from eclipse.org. For example:`John Doe (vogella GmbH) John.Doe@faux.com - Bug 429728 - Stock-still compiler warnings`

If you add a new file don't forget to add the copyright header using the project'due south license. For new files, list "yourself and others" instead of "IBM and others" in the outset line.

If you prepare several bugs in the aforementioned file, you should listing the bug separately every bit in the following example listing. In instance you detect yourself changing the same file over and over once more, you could also use "ongoing maintenance" instead of listing every bug number.

                  /******************************************************************************* * Copyright (c) 2008, 2014 IBM Corporation and others. * All rights reserved. This programme and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html * * Contributors: *     IBM Corporation - initial API and implementation *     John Doe <John.Doe@eclipse.org> - Bug 429728, 429972 *******************************************************************************/                

In most cases you should avert putting in the issues number into the source lawmaking (except the header). Only if you have to implement a workaround for an existing bug, you lot should add together a reference in the source to this problems.

17.half dozen. Stay polite

The best way to go your contribution accepted is to stay polite and to follow the guidance of the existing committers. For the first few contributions information technology is all-time to stay with the electric current processes and guidelines. If y'all continue to contribute, yous volition proceeds more trust and responsibility and yous may be able to amend also the processes used by the project.

17.7. Avoid unnecessary formatting changes

Typically open up source projects dislike if you re-format unchanged lines, equally this makes the review procedure much harder. Avoid pressing the Format source lawmaking shortcut in your editor. Instead, only select the changes lines and then press the format source lawmaking shortcut (this is also an auto-salve preference).

Unnecessary format changes makes information technology actually hard to review a Gerrit change. The following screenshot shows a file which was reformatted, it is unnecessary hard for the reviewer to notice the existent modify.

17.8. Avert unnecessary whitespace changes

Typically projects dislike unnecessary whitespace in the contributed code. Ensure that y'all remove abaft whitespaces from your contributed lawmaking.

Unfortunately lots of projection have unnecessary whitespace included in the source code, nearly committers also don't like if you remove them as it changes the history.

17.ix. Pushing unfinished features

For most projects it is OK to push an initial (unfinished) implementation concept to Gerrit and to ask for feedback.

Mark unfinished commits with [RFC] (request for comments) or [WIP] (piece of work in progress) in the commit message header to avoid frustrating reviewers who typically want to know if the change is considered to be ready by the author or non.

In general y'all should develop in the open up every bit much as possible to avert the unpleasant surprise that your perfect contribution is rejected considering it does non fit into the blueprint of the software.

17.10. Valid user and email

Some project uses boosted validation plug-ins. For example the Eclipse foundation uses a server-side Gerrit plugin which checks for conformity with the CLA. When you push a change to Gerrit this plugin verifies if your contribution passes all the CLA requirements from the Eclipse foundation.

This ways that the author field must be a valid Eclipse user. If the author is not a committer it requires that the writer also "Sign-off" their contribution. Eclipse Git provides a preference to always sign-off changes.

17.11. Not getting feedback

If everything works perfectly, the developers of the project you are contributing to will accept your contribution and aid you to solve all your open up questions.

If you lot don't get feedback in that location are different possible reasons: maybe all committers are busy or in vacation. Or your change is extremely large (hard to review) or it ignores all the rules explained in the project's contributor guide.

If your contribution is ignored, feel gratis to ask in the Problems report for feedback or to ship email to the projection mailing list.

17.12. Dealing with negative feedback

Don't get frustrated past negative feedback, equally the collaboration nigh always results in a amend commit that benefits everyone.

18. Gerrit support in Eclipse

The Gerrit back up in Eclipse is very good, that even customers which use a unlike IDE, use Eclipse as Gerrit customer.

To utilise Gerrit in Eclipse, clone the repository equally seen before, and import your projects. By default, the Eclipse Git tooling creates a configuration that pushes the local primary co-operative to the remote master co-operative. To connect with Gerrit, change the configuration to push the local principal to refs/for/master instead.

Afterward cloning the repository you can configure Gerrit in the Git repositories view by right-clicking on the origin remote and selecting Gerrit Configuration.

You lot can see the Gerrit review notes in Eclipse. Select on a commit in the History View. In the Commit Viewer you have an boosted tab called Notes. Hither you come across the data which was created by the Gerrit reviewer.

keithstent1954.blogspot.com

Source: https://www.vogella.com/tutorials/Gerrit/article.html

Share this post