Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EGit/Contributor Guide"
m (→Coding standards: fix links) |
(→Submission Guidelines) |
||
Line 710: | Line 710: | ||
* if you want your changeset reviewed by someone, please add them as a reviewer | * if you want your changeset reviewed by someone, please add them as a reviewer | ||
+ | == Tips & Tricks == | ||
+ | |||
+ | === Class Loading Issues === | ||
+ | |||
+ | If you encounter strange class loading issues during runtime (e.g. on UI test executions) the following might help: | ||
+ | |||
+ | Enable tracing in your launch configuration to get information how imported packages are resolved at runtime. Select the Tracing tab in your launch configuration, select "Enable tracing", select plug-in org.eclipse.osgi, select category resolver/wiring on the right side. | ||
[[Category:Draft_Documentation]] | [[Category:Draft_Documentation]] |
Revision as of 05:56, 25 November 2011
EGit | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source • Project Set File |
Contents
- 1 Communication
- 2 Development IDE Configuration
- 3 Obtaining Sources
- 4 Builds
- 5 Documentation
- 6 Tests
- 7 Bugs
- 8 Website
- 9 Contributing Patches
- 10 Gerrit Code Review Cheatsheet
- 10.1 Install the commit-msg hook in your repository
- 10.2 To create a new change
- 10.3 To update an existing change with a new commit
- 10.4 To compare bulk diffs using Git
- 10.5 To trigger Hudson build for a change
- 10.6 To approve a change
- 10.7 To add a reviewer
- 10.8 Code Review
- 10.9 IP Review
- 10.10 Submission Guidelines
- 10.11 Tips & Tricks
Communication
Channel | JGit | EGit |
---|---|---|
Developer Mailing List | JGit developer mailing list | EGit developer mailing list |
Build Notices Mailing List | JGit build notices mailing list | EGit build notices mailing list |
Reporting Bugs | File new JGit bug | File new EGit bug |
User Forum | EGit User Forum |
Development IDE Configuration
EGit and JGit have Java 5.0 and Eclipse Platform 3.5 as minimum requirements, so dependencies to newer Java and platform versions must be avoided.
In order to minimize the inadvertent introduction of dependencies to Java 6.0, add both a Java5 and a Java 6 SDK to your workspace. Do this in Window/Preferences -> Java/Installed JREs. Then configure your Execution Environments so that J2SE-1.5 refer to a Java 5 SDK and JavaSE-1.6 refer to a Java 6 installation.
To be completely on the safe side for reducing the risk of breaking Platform 3.5 compatibility, you would have to have a 3.5 IDE ready on which to check your code. In general, the effort for this is probably not justified, unless you are introducing major UI functionality. Just keep the minimum requirements in mind when using Platform API. Eclipse API's are usually marked with a @since tag.
If you are using OS X Snow Leopard, then Java 5 is hard to find. Using the search button in Eclipse will tell you that you have a 1.5.0 version of Java. That is probably a lie. It is just a link to 1.6. Fortunately some nice guys have made a download that you may use. Follow these instructions to download and installl a real Java 5. You do not need to make it default. Downloading, unpacking and fixing the version links is enough.
Libraries from Orbit
Install from Orbit P2 Repository
On the Orbit Downloads page, click on the newest stable build and copy the update site link from "Orbit Build Repository" (it should end with /repository). Add this update site in Eclipse using "Install New Software..." and then find and select the following entries:
- Java Mocking and Stubbing Framework
- Args4j
- Protocol Buffers
Import Team Project Set
The simplest way to import the 3rd party libraries needed to compile JGit and Egit:
- Download the Team Project Set for git dependencies
- File > Import > Team > Team Project Set
- Next
- Select the downloaded GitDependencies.psf
- logon with user "anonymous", leave password field blank
- Finish
Manual Import
Alternatively to importing the team project set, you may do a manual import of the required libraries:
com.google.protobuf
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org:/cvsroot/tools
- Use module org.eclipse.orbit/com.google.protobuf
- Finish
- Right click on the project > Team > Switch to another branch
- Select tag from following list
- Refresh Tags
- Versions > v201105131100
org.mockito
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org:/cvsroot/tools
- Use module org.eclipse.orbit/org.mockito
- Finish
- Right click on the project > Team > Switch to another branch
- Select tag from following list
- Refresh Tags
- Versions > v201102171835
org.objenesis
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org:/cvsroot/tools
- Use module org.eclipse.orbit/org.objenesis
- Finish
- Right click on the project > Team > Switch to another branch
- Select tag from following list
- Refresh Tags
- Versions > v201006030720
org.kohsuke.args4j
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/tools
- Use module org.eclipse.orbit/org.kohsuke.args4j
- Finish
- Right click on the project > Team > Switch to another branch
- Select tag from following list
- Refresh Tags
- Branches > v2_0_12
javax.servlet
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/tools
- Use module org.eclipse.orbit/javax.servlet
- Finish
- Right click on the project > Team > Switch to another branch
- Select tag from following list
- Refresh Tags
- Branches > v2_5
Obtaining Sources
EGit and JGit are self hosted in Git. Browse the repositories in gitweb.
There are several ways to obtain a copy of each repository:
From the command line
git clone http://egit.eclipse.org/jgit.git jgit git clone http://egit.eclipse.org/egit.git egit git clone http://egit.eclipse.org/egit-pde.git egit-pde git clone http://egit.eclipse.org/egit-github.git egit-github
From an installed EGit plugin
First, verify that the default repository folder as set on the main Git preference page is to your liking.
- File > Import > Git > Projects from Git
- Clone...
- Enter URI:
http://egit.eclipse.org/egit.git
- Import existing projects into the workspace from the newly created working directory
To compile properly you will also need libraries from Orbit.
EGit PDE Tools
EGit also provides tools for integrating with PDE Build and Eclipse RelEng Tools. If you are an Eclipse developer using PDE Build and/or the Eclipse RelEng tools you might be interesting in the following as well. Otherwise you might just skip this section.
- File > Import > Git > Projects from Git
- Clone...
- Enter URI:
git://egit.eclipse.org/egit-pde.git
- Import projects
EGit GitHub Integration
EGit also provides tools for integrating with GitHub and Mylyn tasks.
- File > Import > Git > Projects from Git
- Enter URI:
git://egit.eclipse.org/egit-github.git
- Clone...
- Import projects
- Download dependencies:
- automagically: open file
org.eclipse.mylyn.github-feature/github.target
gitweb and select 'Set as Target Platfrom'. - manually: In addition to the libraries from Orbit required for JGit and EGit you also need Eclipse PDE (>= 3.6.1) as well as
org.eclipse.releng.tools
in your target platform or checked out from CVS in your workspaces.
- automagically: open file
Builds
EGit and JGit builds run on build.eclipse.org via Hudson using
Hudson
JGit
- JGit can be built using Maven 2 or 3.
- JGit packaging projects (Eclipse feature and update site) are built using Maven 3 and Tycho.
EGit
- EGit is built using Maven 3 and Tycho.
Mailing Lists
If you're interested in following builds, please check out the following mailing lists:
Maven Build Sequence
- Due to a current limitation of Tycho it is not possible to mix pom-first and manifest-first builds in the same reactor build hence the pom-first JGit build has to run separately before the build for the manifest-first JGit packaging project.
- The 3 builds must share the same local Maven repository otherwise dependencies between these builds cannot be resolved.
- To run the build behind a firewall follow http://maven.apache.org/guides/mini/guide-proxies.html and for Tycho additionally pass proxy settings via system properties (https://issues.sonatype.org/browse/TYCHO-279): mvn -DproxyHost=myproxy -DproxyPort=1080 ...
Complete build sequence for a clean build (assuming $M2_HOME/bin is on the path and local Maven repository at ~/.m2/repository):
[~/src/jgit] $ mvn clean install [INFO] Scanning for projects... ... [~/src/jgit] $ mvn -f org.eclipse.jgit.packaging/pom.xml clean install [INFO] Scanning for projects... ... [~/src/jgit] $ cd ../egit [~/src/egit] $ mvn clean install [INFO] Scanning for projects... ...
The EGit build uses the JGit p2 repository to resolve jgit dependencies. For local builds the build assumes that egit and jgit source trees are located under a common parent folder. If this is not the case the path to the jgit p2 repository has to be injected via system property:
[~/src/egit] $ mvn clean install -Djgit-site=file:/path/to/ org.eclipse.jgit.updatesite/target/site
The hudson build on build.eclipse.org uses:
[~/src/egit] $ mvn clean install -Djgit-site=https://build.eclipse.org/hudson/job/ jgit/lastSuccessfulBuild/artifact/org.eclipse.jgit.packaging/ org.eclipse.jgit.updatesite/target/site/
If you wan to build EGit for the specific Galileo platform, consider using the platform-galileo
maven profile:
[~/src/egit] $ mvn -P platform-galileo clean install
3 such platform profiles are currently available: platform-galileo
(Eclipse 3.5), platform-helios
(Eclipse 3.6), and platform-indigo
(Eclipse 3.7).
FindBugs and PMD
As part of the build, JGit and EGit run FindBugs and PMD to find issues.
Automated Signing and Publishing
EGit and JGit builds are signed and published using the eclipse-maven-signing-plugin via build.eclipse.org to the folder
/home/data/httpd/download.eclipse.org/egit/updates-nightly
To enable this procedure the maven profile build-server
must be
enabled via the option -P build-server
in the egit build job
running at https://hudson.eclipse.org/hudson/job/egit/
Publishing (old method, replaced by automated procedure)
The EGit and JGit builds are published via a shell script on build.eclipse.org (you need SSH access to the machine to publish. At the moment, Chris Aniszczyk (caniszczyk) and Matthias Sohn (msohn) have publishing privileges). There are two scripts that drive the publishing process:
/home/data/httpd/download.eclipse.org/egit/pubegit.sh /home/data/httpd/download.eclipse.org/egit/pubegit-pde.sh
The script essentially fetches the latest successful build from Hudson and publishes it every three hours via a cron job.
Signing (old method, replaced by automated procedure)
To sign the EGit build, you need to have ssh access to build.eclipse.org and the ability to run /usr/bin/sign
At the moment, Chris Aniszczyk (caniszczyk) and Matthias Sohn (msohn) have signing privileges.
The first step is to ensure you're in a place you can sign on build.eclipse.org
cd /home/data/httpd/download-staging.priv/commonBuild
Next you run the signing command (Usage: /usr/bin/sign <file> <mail|nomail> [outputDir]) on a zip of the EGit repo...
sign egit-p2-repo.zip my@email.com /home/data/users/caniszczyk/egit-0.8
After that, you can publish the zip that is generated with the signing information.
Contribution to Release Train
The Indigo release train contribution for JGit and EGit is maintained in the CVS project
extssh://dev.eclipse.org/cvsroot/callisto/org.eclipse.indigo.build
in the file
egit.b3aggrcon
Documentation
The EGit project sources its documentation from the wiki and generates Eclipse help content from it (under the covers, we are using Mylyn WikiText to make this possible). This significantly lowers the barrier for people to contribute documentation to the EGit project. To contribute documentation, simply modify the EGit User's Guide. Have a look at the Style Guidelines and Eclipse Documentation Style Guide to get some guidance on how to write good documentation. More on that can be found here.
The documentation is contained in the org.eclipse.egit.doc plug-in. The build-helper.xml drives the generation of the help content. It is integrated into the maven build. The regular maven build of org.eclipse.egit.doc
$ mvn clean install
will only package the help content committed to the egit repository. To update the help content by downloading the latest documentation from the wiki run
$ mvn clean install -Dupdate.egit.doc
Don't forget to check all the generated help pages and especially all hyperlinks and images before pushing the updated help to the code review system for inclusion into the continuous build.
The aim is to generate new documentation every month or so (or just on demand). If you're making big changes or want the documentation refreshed, please let us know on the egit-dev mailing list.
Tests
JGit Unit Tests
The JGit unit tests are executed during the maven build for the bundle org.eclipse.jgit.test. To run them from the Eclipse workbench use the launch configurations which are part of the sources of the bundle org.eclipse.jgit.test.
JGit HTTP Tests
The JGit HTTP tests rely on the Jetty web container. To run these tests from Eclipse install the jetty feature.
If you are using Helios you can get it from here:
http://download.eclipse.org/releases/helios
Otherwise install it from here:
http://download.eclipse.org/jetty/7.1.6.v20100715/repository
Feature: Jetty - Core: servlets and webapps
For Indigo (you'll need SR1 for that) install "Jetty Target Components 7.5.1.201109140245" from http://download.eclipse.org/releases/indigo. Note: there is a problem with the following Jetty versions 7.3.1.v20110307, 7.4.2.v20110526 which cause the JGit http tests to hang.
EGit Core Tests
The EGit Core tests are executed during the maven build for the bundle org.eclipse.egit.core.test.
To run them from the Eclipse workbench use the launch configuration which is part of the sources of the test bundle org.eclipse.egit.core.test. You will also need to install Mockito, see Libraries from Orbit.
EGit UI Tests
The EGit UI tests are using SWTBot, to run them you need 'SWTBot for Eclipse Testing' feature.
Manual
Install the SWTBot matching your Eclipse version
- Galileo http://download.eclipse.org/technology/swtbot/galileo/dev-build/update-site
- Helios and Indigo http://download.eclipse.org/technology/swtbot/helios/dev-build/update-site
You need to install at least "SWTBot for Eclipse Testing" and "SWTBot IDE Feature".
Starting a UI test from Eclipse:
- select the test class or test method
- click Run As > SWTBot Test
Do not touch the mouse or keyboard when the UI test is running since this may disturb the UI test by e.g. moving the current focus to another window.
Automatic
Using target platform definition file:
- http://egit.eclipse.org/r/382 provides core Galileo-based dependencies and SWTBot for Eclipse Testing feature. You still need JGit projects to be opened in the workspace.
- http://egit.eclipse.org/r/383 extends the previous one with JGit from the nightly update site. This patch makes it possible to develop EGit plug-ins without checking out JGit projects.
How to use it:
- pull either first or both patches
- open Target Platform Preferences page (Window - Preferences - Plug-in development - Target Platform)
- activate 'SWTBot-based UI plug-in tests' target platform
During Maven Build
The tests are executed in the integration-test phase of the default Maven lifecycle.
If you want to skip execution of UI tests during the maven build run
mvn -P skip-ui-tests clean install
Auxilary testing tools
Any code, including testing code, does not always do what you expected it to. The most common failure is probably the failure to actually execute the part of the code you wanted to test. Code coverage tools like EclEmma can easily visualize what part of the code is being executed.
Manual alpha testing
In order to manually test your new feature
- click Run > Run Configurations...
- create a new launch configuration of type "Eclipse Application"
- click Run
- for debugging start the same launch configuration from Debug > Debug Configurations...
also see the reference on eclipse application launchers
Bugs
Links
Filing Bugs
Bug Reports and Links
Trends | EGit | JGit | ||
---|---|---|---|---|
Open Bugs and Enhancements | Open | Open | ||
Assigned Bugs and Enhancements | Assigned | Assigned | ||
All Bugs and Enhancements | All | All | ||
Lists | EGit | JGit | ||
Open Bugs | Open | Open | ||
Open Enhancements | Open | Open | ||
Assigned Bugs and Enhancements | Assigned | Assigned | ||
Reports | EGit and JGit | |||
Open EGit and JGit Bugs | Open | |||
Assigned EGit and JGit Bugs | Assigned | |||
New Bugs opened | Last day | Last week | Last month | Last year |
Bugs closed | Last day | Last week | Last month | Last year |
Keywords
To simplify bug management we started to tag EGit bugs with additional pseudo keywords (not normal Bugzilla keywords). The tags are prepended to the bug's summary field. Since we use these tags for internal bug management reporters of a bug should not add any pseudo keywords when filing the bug. The owner of the component bucket is responsible to add the keywords.
Keywords are used to group bugs without assigning them to a developer. So with the introduction of the keywords it is easy to search for all bugs belonging to a specific sub component. For example to get an overview of all open refactoring issues search for new, assigned or reopened bugs containing the word [refactoring] in the summary field.
Be aware that not all bugs are tagged with keywords, only bugs that belong to a certain sub group may have a tag attached. The following lists some of the currently used tags.
Tag | Description | Link |
---|---|---|
[sync] | everything related to Synchronize / Synchronize View | View bugs |
[repoView] | everything related to the Git Repository View | View bugs |
[releng] | everything related to release engineering and build | View bugs |
[historyView] | everything related to the Git History View | View bugs |
Website
The EGit and JGit websites are located in a CVS repository on the Eclipse Foundation's servers.
egit
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/org.eclipse
- Use module egit (from www)
- Finish
jgit
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/org.eclipse
- Use module jgit (from www)
- Finish
Contributing Patches
Review the following style guides:
Currently the project is using Gerrit Code Review for Git based patch submission and review.
Using Gerrit hosted at egit.eclipse.org with git command line:
- Register a user account
- Use Register New Email to register your email address with our Gerrit Code Review server. This step is required to validate the address is correct.
- Add one or more public SSH keys.
- Execute SSH once to accept the host key (or copy it from the registration web page)
ssh -p 29418 username@egit.eclipse.org
- Confirm you agree to the Eclipse.org Terms of Service by completing the Individual Contributor agreement.
- Upload your patch from Git to the target project:
- JGit
git push ssh://username@egit.eclipse.org:29418/jgit.git HEAD:refs/for/master
- EGit
git push ssh://username@egit.eclipse.org:29418/egit.git HEAD:refs/for/master
- Visit our Gerrit Code Review instance to start reviewing
Or, create a new bug and attach a Git formatted patch file, as produced by the `git format-patch` tool.
Adding a dedicated remote
Since git can have multiple remotes, you can define one to be used to refer to Gerrit to save typing. Inside a previously checked-out repository you can run:
cd path/to/jgit git config remote.review.url ssh://username@egit.eclipse.org:29418/jgit.git git config remote.review.push HEAD:refs/for/master cd path/to/egit git config remote.review.url ssh://username@egit.eclipse.org:29418/egit.git git config remote.review.push HEAD:refs/for/master
You can now submit review requests from either repository using:
git push review
Using Gerrit hosted at egit.eclipse.org with EGit:
- Register a user account
- Use Register New Email to register your email address with our Gerrit Code Review server. This step is required to validate the address is correct.
- Add one or more public SSH keys to Gerrit. If you are absolutely certain you do not have keys already, you must create a public and private pair of SSH keys. It is strongly recommended that you use a passphrase.
ssh-keygen -t rsa -C "your_email@youremail.com"
Eclipse will look for your private key in the SSH2 Home location specified in the General>Network Connections>SSH2 Preference Page. If your id_rsa
private key makes use of the AES-128-CBC algorithm (view the file as text to confirm), Eclipse will need at least com.jcraft.jsch 0.1.44
to make use of it.
- Confirm you agree to the Eclipse.org Terms of Service by completing the Individual Contributor agreement.
- Clone the JGit and EGit repositories and use the last page of the Clone Wizard to configure pushing to the code review queue.
- Alternative approach adding a review remote in the Git Repositories view:
- From the appropriate Remotes node, create a New Remote and choose to Configure for Push. A unique name should be chosen, review is suggested.
- Change the main URI or Add a Push URI (your Gerrit user name must be used here)
- In the Ref Mapping section, Add a RefSpec Specification of
HEAD:refs/for/master
- Changes Committed to your local clone will now be able to be Pushed to Gerrit using the review Remote. You will be prompted for your private key's passphrase if Eclipse is looking for it in the right place.
- Visit our Gerrit Code Review instance to start reviewing
Granularity of Changes
- Make small commits, as small as reasonable. This makes them easy to review.
- Each commit should have a commit message that explains very clearly what the commit sets out to achieve (unless this is abundantly clear from the code itself, which is basically only the case for trivial patches). Also, when you fix a bug then report which bug you fix. When there are deeper reasons for doing things the way the commit does, then explain these as well. This all is for the reviewers and yourself: the context of the commit is completely clear.
- Do not mix concerns in commits: have a commit do a single thing. This makes them reviewable 'in isolation'. The purpose of the commit is clear and can be understood easily by the reviewers and yourself.
- Do not break the build and tests for any commit: this is very important for bug hunting.
- Split your work into multiple smaller pieces of work (when possible) and implement each of these pieces in a series of commits.
- A series of commits should work towards a 'feature' in a clear way and only 'enable' the feature in the last commit of the series.
- In a series of commits first lay the groundwork and then build on that towards the feature.
- Do not mix concerns in branches: when you encounter a bug while working on something then create a new branch to fix the bug. If your work depends on the bug being fixed then rebase your work on that new branch.
Coding standards
Eclipse has standards for how to write code.
These documents have links to other document. Browse through them without expecting to learn everything, just so you know roughly what areas and types of details they covert. When you are not sure about how to write a piece of code or design the user interface, these are the two first places to look at.
In addition there is all the worlds collective knowledge on how to write programs that shine. When there is a conflict, the Eclipse guide lines and conventions take precedense.
Breaking the rules is ok if there is a very good reason and you can tell us what that reason is.
In addition to these general rules, we regard performance high. If the EGit plugin is slow in any way, that is a bug and should be reported and fixed. Java isn't slow, but there is a lot of slow Java code.
Commit message guidelines
- The commit message header should fit on one line and should start with an uppercase letter
- The commit message have newline characters after every 60-70 characters.
- Find more reasoning about commit message formatting in "A Note About Git Commit Messages"
- If a Gerrit Change-Id is available (for example when re-submitting to the same change), it should be added in the format below
- If there is an associated bug number in Bugzilla about it, it should come right before Gerrit's Change-Id entry (if available) or towards the end.
- A "Signed-off-by" should be added to the end of the commit message (see example below).
- The first sentence should be a clear and concise description about the change.
- Enter a newline before providing a more detailed description about the change.
Fix the commit dialog to respect the workbench's selection Originally, the commit dialog would automatically check off all files in the dialog. This behaviour contradicts a user's expectation because their selection in the workbench is completely ignored. The code has been corrected to only preselect what the user has actually selected. Bug: 12345 Change-Id: I71ac4844ab9d2f848352eba9252090c586b4146a Signed-off-by: Your Name <your.email@example.org>
Test before submitting
See the #Manual alpha testing section for some advice about how to test you work yourself.
- Run all existing tests. It does not take very long.
- Pay attention to the Java and Eclipse SDK baselines. EGit requires only Java5 and Eclipse 3.5. You cannot use API's that are newer. We often see breakages because Java 6 API's are used.
Note: In order to test in Eclipse 3.5 (Galileo), consider building EGit with the platform-galileo
maven profile (see the #Maven Build Sequence for more details).
Sending patches by mail
Although sending patches by mail is the approved way of interacting with, and asking feedback from, the Git project, please don't send patches via git send-email. Instead, please use git format-patch to generate the mbox
, and then attach that to an item in bugzilla as per the above SUBMITTING_PATCHES guides.
If you're sending a work-in-progress for a review, be aware that you can also attach work-in-progress (or RFC) items to Bugzilla; it's not just for finished patches.
However, it's generally preferred that you send items which you want comments on via Gerrit as per #Adding_a_remote, since Gerrit allows comments to be added in-line and allows the opportunity to send multiple versions of a patch after changes are made. Once a change has been submitted to Gerrit, you can then mail the developer mailing list with a request to review your change via URL or get Gerrit to send the mail on your behalf.
Gerrit Code Review Cheatsheet
Install the commit-msg hook in your repository
scp -p -P 29418 username@egit.eclipse.org:hooks/commit-msg .git/hooks/
This will ask for a password. It is the password that you have to generate in the SSH Keys section of settings in your Gerrit account.
You can alternatively download the file. The hook helps append a Change-Id to your commit message.
To create a new change
- JGit
git push ssh://username@egit.eclipse.org:29418/jgit.git HEAD:refs/for/master
- EGit
git push ssh://username@egit.eclipse.org:29418/egit.git HEAD:refs/for/master
Or, if you've followed the instructions on #Adding_a_remote you can simply do:
git push review
Since the current repository has the right definition for 'review', you won't need to remember the canonical push URL
To update an existing change with a new commit
git push ssh://username@egit.eclipse.org:29418/egit.git HEAD:refs/for/master
This works because Gerrit links the new commit to the prior change based upon the Change-Id footer in the commit message. (This is automatically generated by the commit-msg hook you installed above.) If you refuse to use the commit-msg hook, or don't have a Change-Id footer, you should read the Gerrit documentation on change-id lines and replacing changes.
Note: To be picked up by Gerrit, a Change-Id line must be in the bottom portion (last paragraph) of a commit message, and may be mixed together with the Signed-off-by, Acked-by, or other such footers. So if your Change-Id line is ignored it's probably not in the last paragraph :).
To compare bulk diffs using Git
Since each Gerrit review patchset actually commits its own tree, you can pull out the trees and compare them.
If you've got a large changeset, and you want to be able to do diffs between them via (command line) git instead of browsing on the web, then you can fetch the individual changes and then perform a diff. For example, http://egit.eclipse.org/r/2 shows the 'download' section for each patchset. In this case, it looks like:
- Patch Set 1
git pull git://egit.eclipse.org/jgit refs/changes/02/2/1 (1d3331a91bd477d3f70cde9613576cf9688ac358)
- Patch Set 2
git pull git://egit.eclipse.org/jgit refs/changes/02/2/2 (13ab9a43d4d512963556a92e889b1204d32f8e68)
- Patch Set 3
git pull git://egit.eclipse.org/jgit refs/changes/02/2/3 (d14cc645655683ba3e30a35833fb2282142e898f)
- Patch Set 4
git pull git://egit.eclipse.org/jgit refs/changes/02/2/4 (43de8d385b614c72fd796e17da75d381f6e0cc25)
Performing a git pull
will both get the bits and merge them into your tree, which won't do what you want for comparison. So, in order to get the bits (but not merge), you need to do a git fetch
instead. Let's say we want to diff the last two patches against each other rather than reviewing the entire patchset again:
git fetch git://egit.eclipse.org/jgit refs/changes/02/2/3 git fetch git://egit.eclipse.org/jgit refs/changes/02/2/4 git diff d14cc645655683ba3e30a35833fb2282142e898f 43de8d385b614c72fd796e17da75d381f6e0cc25 # or git diff d14cc6 43de8d
If you're doing this from within an already checked out project, you can do git fetch origin
(or any other remote name in .git/config}
.
Git fetched data will stay around in your repository, but will be 'orphaned' if no references point to it. To clean up, you can run git gc
or wait until this happens automatically.
To trigger Hudson build for a change
- Go to Trigger a Gerrit event manually page
- Search for a change you'd like to build
- Select the patch set(s) you want to trigger
- Press Trigger Selected button
To approve a change
- Click on Publish Comments
- Vote with the radio buttons
To add a reviewer
Once you've pushed your commit to Gerrit for review, you can go to the web page (http://egit.eclipse.org/r/) and see your changes. By clicking on the review, there's an option to add a reviewer by e-mail address; they'll then be sent a message indicating that they'd like your review on the item.
Code Review
The code review category indicates your opinion on the quality of the code, and how well it fits within the purpose of the existing surrounding code. A +2 vote from any committer is required before submission can occur. A -2 vote from any committer will block submission.
IP Review
The IP review category indicates whether or not the change has been properly logged under the eclipse IP process. Under that process, any committer should mark his/her change +1 if they were the sole author of the change. For any other change, a committer should only mark +1 after ensuring the corresponding bug in Bugzilla has been updated with the iplog flag, or the corresponding CQ has been marked checkintocvs. For contributions from external contributors have a look at the detailed rules. A +1 vote is required to submit a change, while a -1 vote will block submission.
Submission Guidelines
We strive to use Gerrit to improve our understanding of the code base and improve quality.
In order to ensure a proper review happens, some simple guidelines should be followed:
- vote 0/-1 for not-ready-to-submit (AKA WIP) own proposals, +1 otherwise;
- If a changeset is not-ready-to-submit, please put [RFC] or [DRAFT] in the message to let people know
- let non-trivial changes be in review for at least 24 hours
- if you want your changeset reviewed by someone, please add them as a reviewer
Tips & Tricks
Class Loading Issues
If you encounter strange class loading issues during runtime (e.g. on UI test executions) the following might help:
Enable tracing in your launch configuration to get information how imported packages are resolved at runtime. Select the Tracing tab in your launch configuration, select "Enable tracing", select plug-in org.eclipse.osgi, select category resolver/wiring on the right side.