What PTP contributors (committers and others) need to do for the basic tasks
PART 1 - What PTP contributors need to do to add a proposed fix/patch to Gerrit
- Clone the repo (see Environment setup page section on setting up the git repo for more details). Pay particular attention to the URI for the repo, which Gerrit needs.
- Open a new bug for PTP if no bugzilla entry exists yet (this is a good place to discuss the bug fix and how to proceed)
- Unless a change requires a previous commit, a change for Gerrit should always be made directly on top of the latest upstream version (without any other local commits in the history). You have two options:
- Reset: Team->Reset. Then choose Remote->origin/master and "Hard". WARNING: This resets everything in your current branch.
- Checkout: Team->Switch To->Other. Choose Remote->origin/master. You get a warning that you should't make commits because they wouldn't be visible. You can ignore that warning as long as you upload your change before switching to another branch. If you want to switch before uploading you should create a local branch before switching.
- Make changes to the code
- Commit the changes (to local repo) making sure that the commit includes the bug id and Signed-off-by and Change-Id lines#. The bug id should be in the commit message, and the UI provides buttons for the additional lines. Team>Remote>Push to Gerrit...
- Put a link to the Gerrit info in the bug
- If you want to upload another new change make sure to redo the reset/checkout step.
See also Using Gerrit for CDT as our use should be similar/same.
PART 2 - What a committer needs to do to review a patch (review changes, download the patch, and later commit it to the repo to get in the build).
- Navigating to a change
- Go to the URL for the change - should be in the list of PTP Gerrit changes at https://git.eclipse.org/r/#/q/status:open+project:ptp/org.eclipse.ptp,n,z
- Click on the correct subject
- The most recent changes (patch set) should be open (each patch set represents a single commit)
- Reviewing a change
- Click on each file (list under the "File Path" heading) to see e.g, a diff viewer of the changes, comparing old and new. Review the changes, add comments to the author in line if required
- To add an inline comment, click on the line number on the far right in the diff viewer
- On the main screen, click on the "Review" button
- If you wish to now vote
- Verified: choose +1, 0 or -1 (+1: downloaded and tested, 0: not tested (only code review), -1: doesn't work)
- Code Review: choose +2 to -2 - A +2 indicates approval of e.g. a committer - this accepts the change.
- IP-Clean: +1, 0, -1 ( +1 is required to finish and push the change)
- Overall comment can be entered at bottom as "Cover Message"
- Be sure to "Publish Comments" in order for author/contributor to be notified and for comments to be visible
- Once there is a +2 vote for "Code Review", +1 for "Verified", and +1 for "IP-Clean", use "Publish and Submit" to ... to push the changes to the main repo
- Downloading a change
- The "Download" field on the main screen shows different ways of obtaining the changes in order to test in your local repo (from command line only)
- Issue the command in the directory that is the location of the git repo.
- this will create a new branch for the changes, change the repo so this is the default branch, and your eclipse workspace will be changed -- within a few seconds -- to show that branch.
- Test this change within this new branch now in your workspace, if desired.
- If the change is successful, at the bottom of the page, under "Comments" you will see "Change has been successfully merged into the git repository."
- If the change is rejected, the contributor can upload a new patch set, then the process is repeated
- Watch emails and follow links for more information -- may provide more information.
- Now switch your Eclipse workspace back to master (Rightmouse on a project, Team > Switch To > master) and do a pull (Team > Pull) and you should see the change come in.
We also plan to add an auto build step so that hudson will automatically try to build with the change (and run tests too). If the build succeeds, hudson will vote on the change. The Gerrit-based build is separate from the build based on code committed to the repository.
PART 3 - What PTP contributors need to do to improve a change
- Switch to change. Options:
- Team->Remote->Fetch from Gerrit. URI: See part 1, Change: the change number, then press ctrl+space, Action: any works. Checkout is probably sufficient.
- If you created a local branch in Part1 (as part of checkout), then you can use Team->Switch To
- Commit with amend. Make sure the "Amend previous commit" button (right of "Commit message") is on.
- It is recommended to reply to every review message on the Gerrit website to make sure that no comment is overlooked. If all you want to say is that you have done the requested change, click "Reply done".
PART 4 - What PTP contributors need to do to update to latest upstream changes
- To pull the changes:
- If you are currently on a local branch:
- If you're not sure verify that you have pull configured to "Rebase": Select the branch in the "Git Repositories" view, Right-click Configure. Rebase should be selected
- If you are not on a local branch or you don't have it configure for rebase
- Team->Fetch from Upstream
- Team->Rebase, Remote Tracking, Select the remote branch
- If you are currently on a local branch:
- If there are merge conflicts, resolve them. After you resolved the conflicts commit without amend.
- The pull may change the author of the commit. If this happens, "git commit --amend --reset-author" should fix the issue.