Push a Change to Meta Config in Gerrit for Review

Gerrit tutorial. This tutorial explains the installation and usage of the Gerrit code review system. It describes the setup of Eclipse (with EGit) as well every bit the control line setup.

1. Code review

1.1. The code review process

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

In one case a modify is accepted, people with the right 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 take changes

A code review process can be implemented without any tool support. Just it is typically more than efficient, if a structured code review system is used.

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

In general a structured code review procedure has the following advantages:

• Early mistake detection:

  • Build issues are detected immediately by automatic test builds.

  • Logical flaws can be spotted by the human reviewer earlier any code is merged.

• Alignment with project standards:

  • Allows the team to identify early in the process whatever violations with the team code standards.

  • Helps to keep code readable and easier to maintain.

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

• Knowledge exchange:

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

  • Developers can get feedback on their suggested changes.

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

  • Shared code buying: by reviewing code of other developers the whole team gets a solid knowledge of the complete code base.

• Like shooting fish in a barrel entry to contribution: People without write permission to a repository have an like shooting fish in a barrel fashion to first contributing and to go feedback.

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

For an efficient procedure, the code review should be conducted in a supportive environment where effective feedback is given to heighten the change.

1.2. The Gerrit code review system?

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

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

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

Gerrit makes code reviews easier past showing changes in a side-past-side display. It besides supports to display the modify every bit a unified diff which is often easier to read on smaller screens.

A reviewer tin can add comments to every single line inverse.

Gerrit is licensed under the Apache 2.0 license.

The Gerrit review system uses the term change, to define a code review / review request. Each change is based on ane commit.

ane.iii. How does Gerrit piece of work?

Gerrit can prevent users from pushing direct to the Git repository. If you push to Gerrit, you utilise a certain path ( ref specification) which tells Gerrit that you lot want to create a alter. This push ref specification is refs/for/chief if the target of the change nether review is the master branch. You can besides push button to refs/for/xyz to put a commit into the review queue for the xyz co-operative.

If you push to this ref specification, Gerrit creates a new change or makes an update of an existing one. Gerrit uses the Change-Id information in the commit message to identify if the push is a new commit or an update of an existing change.

A change consists of one or more patch sets which are used to improve the starting time proposal based on review comments. One patch set corresponds to one Git commit.

It is however possible to bypass lawmaking review by pushing directly to refs/heads/master if sufficient rights accept been granted.

ane.4. Review categories - Verified and Code-Review

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

In typical installations as well the Verified category is installed.

The Verified category typically ways you were able to build and test the modify introduced with the Gerrit modify. Typically, this is washed by an automated process such as a Jenkins / Hudson build server.

The "Code-Review" category is typically used to vote on the quality of the implementation, code mode, code conformity. It as well indicates that the change is in accordance with the standards desired past the project.

Committers and contributors can vote in these categories.

i.5. Voting in Gerrit

The rules for voting in Gerrit is:

• Highest vote (+2 in Lawmaking-Review and +one in Verified) enables submitting

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

• You cannot submit the changes to the Git repository until at that place 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 you desire and so it is good to +1 in the "Verified" category. Or requite -ane if it failed some of your apply cases that must exist resolved in club to merge. Otherwise, exit it every bit 0, if you did non test the code.

Not-committers of the project tin can vote with -1 and +one to indicate an opinion in either manner. But ultimately information technology is upward to the determination of those with +two power to make the overall conclusion. You may want to -ii vote to cake the submission of the code. Or vote +2 to indicate that you approve that the contribution is merged into the Git repository.

1.6. Posting typhoon reviews

There is also a special refs/drafts/primary refspec which you tin utilise to push changes to for private review before publishing them to all developers.

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

ii. Installation of Gerrit

The installation of Gerrit can be washed direct on a server or inside a Docker container.

2.1. Installation of Gerrit on a server

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

2.i.1. Download Gerrit

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

The post-obit clarification uses the approach to get-go the Gerrit server directly via the command line.

two.1.2. Setup of Gerrit

Copy the .war file into an empty directory.

Switch on the command line to the location of the directory to which y'all extracted the .state of war file. Install Gerrit with the following control.

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

If Java does non find the jar if you employ *, use the full name. This is for example required on Microsoft windows.

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

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

Tabular array 1. Gerrit setup options

Option	Description
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, by default it uses a preconfigured H2 database.
Run as user	Select that Gerrits runs equally "root" user.
Listen on port	Allows y'all to configure the port Gerrit is listening to, Gerrit by default listens on port 29418 for SSH access and on port 8080 for spider web access. This can be changed if the ports are already used.
Hallmark method	Typical configuring to admission the Gerrit server uses LDAP or OpenID Single Sign-on which is the default setting. Use ? to run into all available settings for this pick. For testing employ "development_become_any_account".

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

2.1.3. Kickoff Gerrit server

Subsequently a successful installation Gerrit starts automatically on Unix-like systems. You can kickoff and stop information technology again with the following commands on Linux based systems.

                                          #                                            assumes you installed Gerrit                      in                      #                                            the abode directory nether gerrit                                                                  #                                            start                      if                      not running                      ~/gerrit/review_site/bin/gerrit.sh start                                            #                                            stop it again                      ~/gerrit/review_site/bin/gerrit.sh terminate                                      

On Microsoft Windows based systems you need to invoke the daemon direct. If you created your Gerrit installation in the folder 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 process using Ctrl+C .

If something goes wrong, expect into the logs folder.

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

3. Gerrit workflow

3.1. A typical Gerrit workflow

The following describes a typical Gerrit workflow of you every bit a programmer using Gerrit.

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

• Optionally, you lot create a new local branch based on the origin/master branch.

This step is optional only information technology is considered a adept practice to create an independent branch per change to avoid unnecessary dependencies betwixt commits (Gerrit reviews).

• You lot implement a change (new characteristic, problems fix, documentation change) and create a commit in his local repository with these modifications.

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

Later you perform the post-obit steps.

• Push the change to the Gerrit review organization to the refs/for/principal refspec to create a change for the chief branch.

• If you lot receive comeback suggestions, fetch the latest changes and rebase your patch onto origin/master

Repeat the concluding three steps until the patch is finally accepted and merged into the codebase (or until the change is completely rejected). Finally you lot tin delete your local branch.

3.2. Gerrit vs. Git workflow

In the Gerrit scenario amending a commit is used to update the Gerrit change asking. Using the better functioning on a published commit is usually discouraged in Git, in Gerrit it is the normal procedure.

iii.3. Gerrit vs. GitHub workflow

The Gerrit review system is based on the supposition that each commit is reviewed separately. At GitHub, a consummate branch is reviewed and merging with the pull request.

4. User setup

iv.1. Create user

Y'all require a valid Gerrit user to piece of work with Gerrit. In your exam installation, you lot create your own users.

If you are not the administrator, you have to ask the responsible person to create a user for y'all.

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

http://localhost:8080/login/

The first user to login automatically gets the ambassador status.

iv.two. SSH setup

If y'all desire to utilise SSH you have to upload your SSH central. If you prefer to utilise HTTPS, skip this step and get to HTTPS setup.

From the user drop downward carte du jour select Settings and select SSH Keys to upload your public SSH key.

Based on your SSH key you are now able to exchange data with the Gerrit server.

Select Profile to assign a Username to your user.

iv.three. HTTPS setup

Y'all tin as well enter a password for HTTPS access.

5. Administrator: Upload Git repository

This part is only relevant for the administrator. Create a new Git repository called gerrittest via EGit or the Git control line.

Create a the new Git repository in Gerrit via the post-obit 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 projection can be found in the Gerrit web interface under .

Select your project and . For testing give button rights to all registered users, which is the default after a fresh installation. In a productive surround, you lot can configure Gerrit to be more restrictive. Especially the admission correct Push Merge Commit for feature branches named refs/heads/* is something only trusted and experienced committers should be allowed to practice.

6. Ambassador: Create case projection

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

Afterwards button the local Git repository to Gerrit by selecting . Enter the post-obit URL ssh://<userid>@localhost:29418/demo/gerrittest.git in the wizard and press the Adjacent push button.

On the adjacent folio, click the Add All Branches Spec button.

Press the Next button and on the terminal sorcerer folio the Stop push.

This pushes the changes directly to the Git repository without a modify in Gerrit. This is possible every bit the default permissions in Gerrit are prepare to allow this.

vii. Project Owner: Editing the project config through Git

Each Gerrit project is configured via a projection configuration file. You tin can edit the projection configuration via the webuser interface, nether .

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

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

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

Bold your projection is lacking the "Verified" label you lot could add together the following to the config:

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

After yous have commited your changes you lot can push them:

                                  git push button -f gerrithub  Head:refs/meta/config                              

8. Project Owner: Managing project access

Projection access in Gerrit is mostly handled through Groups, although yous tin can as well fix permissions on a per user basis. An open source projection might have a grouping for commiters, who can review and merge changes, and a group for their CI solutions. To create a new group navigate to .

Once yous take created a group you are taken to the group management folio, where you tin can add new members to the group.

After that y'all can give this Grouping access to your project. This is washed either through the web interface at or by editing the projects config file every bit described in Project Owner: Editing the project config through Git.

9. Programmer: Clone repository from Gerrit

In this exercise you act as a developer who wants to upload a Gerrit review. This requires that you accept a valid Gerrit user on the Gerrit system.

For this exercise, it is assumed that you have not nonetheless a local Git repository. Therefore, yous demand to clone the Git repository from the Gerrit server. Use a new workspace for this.

Open up the Git Repositories view in Eclipse and select that you lot 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. Developer: Gerrit configuration for the Git repository

If you 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 footstep.

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 Finish push.

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

Utilise the Properties view on your repository to see the details of your repository configuration.

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

You tin can also practise this setup direct via the Git control line.

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

11. Creating and updating a Gerrit change request from Eclipse

In the following description nosotros create a Gerrit change asking.

After getting the latest source code, when yous are ready for development, create a new local branch starting from the origin/master branch.

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

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

Push the modify to Gerrit. Equally your push configuration is configured for Gerrit, this should create a alter. The Eclipse Git tooling shows a dialog afterward the push. This dialog contains fault letters in case the push was not successful. Via the URL yous tin can access the Gerrit spider web interface and analyze the Gerrit review.

Practice a few new changes to your Java project and commit them to your local Git repository. Ensure that you lot amend the existing commit. This makes sure the existing modify id is used and avoids that Gerrit cannot apply your change because of a dependency cycle on the commits. Push your new commit to Gerrit, this should update the existing review asking. The Eclipse Git push button confirmation dialog should tell you that you created a new change 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 you take two Gerrit change reviews, instead of ane.

Hither is what y'all have to do to combine them:

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

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

• Select the terminal commit before the two commits which you want to combine

• Correct-mouse clicke and select Rebase Interactive

• In the Rebase view, select Fixup on the second commit to combine ii commits using the commit bulletin from the starting time commit.

• Press Offset to run the interactive rebase

• Push the changed commit to Gerrit, this will update the first Gerrit, as the Change-Id is all the same the same.

• Abandon the 2nd commit

xiii. URL for reviews

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

which is the default port for a local Gerrit installation. You run into all change requests, if you lot login into the Gerrit instance you run across Gerrit changes you are involved with.

14. Using the Gerrit web interface

14.one. Reviewing a alter request

Click on ane alter request to see the details of the Gerrit change asking. Click on the commit bulletin of the file name (highlighted in the screenshot) to encounter the changes in the file.

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

Clicking on Upwardly to alter brings you back to the alter.

Gerrit allows y'all to review the commit message, which appears at the peak of the file list. To sympathise the history of the repository it is important to provide a good commit message.

14.2. Publishing your review result

Click on Reply button to give feedback on the change.

You lot can give a summary of your feedback and render a review number betwixt -2 and +2 (if you are a committer) or between -1 and +i (if you are non a committer). If you vote -1 or -2, you respectively betoken that the patch still requires rework or that you lot disagree with the suggested change. Encounter Voting in Gerrit for details of the default voting rules.

14.3. Amend a modify based on review feedback

If the review process has resulted review comments explaining how to better 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 can also adjust the commit message while amending the commit.

Every bit the programmer amends the commit, the aforementioned Modify-Id is used and the Gerrit review organisation identifies the change as update of the existing change.

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

Gerrit allows you lot to select which patch sets yous desire to compare in Comparing view. Typically you compare the base of operations version with the latest patch set up, but if due east.k. you already reviewed patch prepare three y'all may desire to simply run into what the writer changed betwixt patchset 3 and patchset 5.

Once the modify has reached the required quality, the reviewer can give a +2 evaluation of the alter.

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

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

14.four. Keyboard shortcuts in Gerrit

Press the "?" primal in the Gerrit spider web user interface to see the actions you can trigger via shortcuts. The bachelor shortcuts depend on at that place you are in the user interface.

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

14.5. Fetching a remote change into a local Git repository

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

After fetching a modify, the developer tin can adjust the change and amend the commit. If he pushes it to Gerrit, the change is updated. Such a procedure should exist coordinated by the writer of the original change to avoid that ii developers do the aforementioned work.

14.vi. Fetching a remote alter with Eclipse Git

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

When working with many projects, it is often easier to right-click on the repository instead and access Fetch from Gerrit from there. Y'all can paste the modify's number (shown in the modify'southward URL) and use Ctrl+Space to aggrandize the modify number to the list of patch sets. Select the one you want to download and fetch it into a new local co-operative. Afterwards you tin can test the changes in isolation.

14.vii. Edit a change directly via the web interface

You can also edit directly in Gerrit. Press the edit push for this.

Afterward select the file or the commit message you want to edit. Printing relieve and shut once you are done. Later y'all are done with all your edits, printing the Publish Edit.

fifteen. Solving typical Gerrit problems

15.one. You forgot to amend the commit

If you effort to push a commit which contains the same ChangeId equally a predecessor commit, Gerrit rejects it and responds with the mistake bulletin: "squash commits first".

In this case you probably forgot to amend the existing commit and used the same Gerrit Change-ID. This is depicted in the post-obit graphic.

In this case you need to squash the commits. This results in a new commit which tin be pushed to Gerrit. As yous use the aforementioned Change-ID this pushed commit updates the Gerrit review. In the following diagram the "Commit 2'" is the effect of squashing "Commit ii" and "Commit 3" into one commit.

An easy solution to handle this is, to practice a soft reset in Git to the previous commit and commit the alter files once more, this time with the amend selection. If you really intended to create two commits yous 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 you want to squash in the History view and by selecting from the context bill of fare.

15.two. Handling merge conflicts

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

The easiest way to exercise so is via the Rebase button in the Gerrit web interface, if there are no conflicts.

In case you have to resolve merge conflicts you take to do this locally and push an updated commit. The steps required to solve a merge conflict are:

• Rebase your local branch onto the latest land of origin/chief

• Resolve all conflicts

• Commit them using

• Push your change again to Gerrit for review

This creates a new patch set for the change. The new patch set has to pass the code review again. Submit the new patch set change to merge it into the principal branch.

15.3. non-fast forward

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

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

In this case the pushed commit is not 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 you lot button the commit again to Gerrit.

16. More infos on problem shooting

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

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

In this case, y'all cannot merge the other commits equally they however have a dependency to the "bad" commit.

During the review process commit two are rejected. The commit 3 and commit 4 are even so good and do not depend on the changes in commit 2.

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

The Gerrit user interface does prove "depends on" and "needed by" fields when it 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 project

17.1. How to start contributing?

It is typically a good approach to ready something actually simple as the commencement step. Search for a few alarm messages in the code, or a typo in the documentation, and set a fix for it.

One time you get familiar with the contribution process first contributing something more than difficult.

17.2. Telescopic of a Gerrit change / commit

A Gerrit modify (== one commit) should accost only 1 issue.

Avoid going "off topic" with your patches. If you would like to clean up some code, or ready something out of the telescopic of your patch, create additional patches. This will brand your patches more concise, easier to review and easier to revert if something get incorrect.

In many open source projects smaller patches tend to be reviewed faster and merged faster every bit it is easier for the committer to review. With this in mind, try to suspension your contributions into small concise Gerrit changes. Information technology is more than likely that these get reviewed and accepted.

It also helps to achieve a make clean history. Imagine you are chasing a problems in code which was introduced two years back. If the history is congenital from small concise commits, it is easier to observe the commit which introduced the problem and understand the motivation why it was done in the way it was implemented.

17.3. Commit message

Well-nigh project handles the required commit message a bit differently. For example, the Eclipse Platform project prefers the following format:

                                      Problems                    XXXXXXXX                    -                    bug                    title                    Short                    description                    of                    what                    the                    fix                    contains                    ,                    or                    the                    direction                    of                    the                    fix                    Alter                    -                    Id:                    I0000000000000000000000000000000000000000                    Signed                    -                    off                    -                    by:                    email                    -                    from                    -                    the                    -                    CLA                                  

The text in the header must match the title in Bugzilla. The Eclipse Git tooling complains virtually commit headers longer than eighty, but you can ignore this warning. For example the post-obit is a valid commit bulletin for the Eclipse platform projection. The description in the body of the commit message can accept as many lines as necessary and should exist descriptive of what is going into the patch. For more circuitous patches you should provide implementation details and enough notes to allow the reviewer to understand what your fix provides.

                  Bug 434846 - Update the system default Locale if the -nl Locale is invalid  An wrong locale value causes the IEclipseContext to run the conversion frequently. The patch ensures that just valid values are saved in Eclipse context.  Change-Id: I6099172a5986e9678a830f84d78b2cdb8c161dc6 Signed-off-by: Dirk Fauth <dirk.fauth@fake.com>                

It is of import to explicate in the commit body, why the change was done. Likewise explain why yous take chosen a sure implementation method, if in that location was something special virtually it.

Don't worry too much about the correct commit message format, the project you lot are contributing to volition also review your commit message.

In some projects the source file contains a copyright header. If you alter the file you should also update the copyright header. Dissimilar project might apply different standards here. Have a look at existing commits and the header in the existing files and endeavour to conform the style preferred by the existing developers.

Well-nigh Eclipse projects to not required to update the copyright header. Optionally you lot can besides add yourself to the copyright with a reference to the issues and update the copyright header with the last modified yr. The following list shows an case for this standard.

                  /******************************************************************************* * Copyright (c) 2008, 2015 IBM Corporation and others. * All rights reserved. This program 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@fake.org> - Bug 429728 Fix compiler alarm *******************************************************************************/                

The in a higher place file was created in 2008 and concluding modified in 2015. It was originally created by employees of IBM and too modified by John Doe and he stock-still Bug 429728 with it. The additional entry in the Contributors section is typically considered optional, but this depends on the individual project.

If you lot work for an arrangement the Foundation recommends adding the organization proper noun in parentheses. Run across: Copyright info from eclipse.org. For example:`John Doe (vogella GmbH) John.Doe@imitation.com - Problems 429728 - Fixed compiler warnings`

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

If you fix several bugs in the same file, you should list the bug separately as in the post-obit example list. In case y'all find yourself irresolute the same file over and again, yous could also use "ongoing maintenance" instead of listing every issues number.

                  /******************************************************************************* * Copyright (c) 2008, 2014 IBM Corporation and others. * All rights reserved. This program and the accompanying materials * are fabricated 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 avoid putting in the bug number into the source code (except the header). Only if you take to implement a workaround for an existing bug, you should add together a reference in the source to this problems.

17.half-dozen. Stay polite

The all-time way to get your contribution accepted is to stay polite and to follow the guidance of the existing committers. For the first few contributions it is best to stay with the current processes and guidelines. If y'all continue to contribute, yous will gain more trust and responsibility and you lot may exist able to improve also the processes used by the project.

17.7. Avoid unnecessary formatting changes

Typically open source projects dislike if yous re-format unchanged lines, equally this makes the review procedure much harder. Avoid pressing the Format source code shortcut in your editor. Instead, only select the changes lines and and so press the format source code shortcut (this is likewise an auto-save preference).

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

17.8. Avoid unnecessary whitespace changes

Typically projects dislike unnecessary whitespace in the contributed code. Ensure that you lot remove trailing whitespaces from your contributed code.

Unfortunately lots of project have unnecessary whitespace included in the source code, most committers also don't like if you lot remove them every bit it changes the history.

17.9. Pushing unfinished features

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

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

In general you should develop in the open up as much as possible to avoid the unpleasant surprise that your perfect contribution is rejected because it does not fit into the design of the software.

17.10. Valid user and electronic mail

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

This means that the writer field must exist a valid Eclipse user. If the author is not a committer information technology requires that the writer also "Sign-off" their contribution. Eclipse Git provides a preference to e'er sign-off changes.

17.11. Non getting feedback

If everything works perfectly, the developers of the project you are contributing to will take your contribution and help yous to solve all your open questions.

If you don't get feedback there are unlike possible reasons: perhaps 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, experience free to ask in the Bug written report for feedback or to ship e-mail to the project mailing listing.

17.12. Dealing with negative feedback

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

18. Gerrit support in Eclipse

The Gerrit back up in Eclipse is very skilful, that even customers which utilise a dissimilar IDE, apply Eclipse equally Gerrit client.

To use 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 master branch to the remote primary branch. To connect with Gerrit, modify the configuration to push the local principal to refs/for/master instead.

After cloning the repository yous tin can configure Gerrit in the Git repositories view by correct-clicking on the origin remote and selecting Gerrit Configuration.

You can run into the Gerrit review notes in Eclipse. Select on a commit in the History View. In the Commit Viewer you have an additional tab called Notes. Here you meet the information which was created by the Gerrit reviewer.

murrayacce1997.blogspot.com

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

Share this post