...
You will need to authorize Gerrit to access some details of your Github account, and then you should be brought back to the Gerrit homepage. Unfortunately, there's a bug in the Gerrit OAuth plugin that will send you to a page that gives a 404 error. You'll need to manually go back to https://gerrit.cloudera.org/, and at that point you should be signed in as 'Anonymous Coward (X)'.
If your Gerrit username is different than your username on the system you want to send patches from, set your "GERRIT_USER" environment variable to your Gerrit username.
Add your public SSH key
Once you are logged in, click your user name in the top-right corner, and go to 'Settings'. Under 'SSH Public Keys' you'll need to paste in your public key:
cat ~/.ssh/id_\{r or d\}sa.pub
While you're in the settings page, please make sure to update your profile with your name, and your e-mail address!
Configuring Gerrit as a Git remote
It's reported that RSA keys are denied in new OSes like Ubuntu 22.04 and MacOS 14 (Sonoma). Try other key types like edcsa or ed25519, e.g. try one of these
Code Block |
---|
ssh-keygen -t edcsa -b521
ssh-keygen -t ed25519 -b 4096 |
While you're in the settings page, please make sure to update your profile with your name, and your e-mail address!
Configuring Gerrit as a Git remote
Gerrit works by keeping a Git repository for all the projects it maintains, including Impala. The source of truth for what is in Impala is the Gerrit works by keeping a Git repository for all the projects it maintains, including Impala. The source of truth for what is in Impala is the official Apache git server. Gerrit serves as a staging ground for reviewing patches, and once a patch is approved, a sort of waiting room while patches wait for a committer to officially move them to the Apache git repo.
...
To set up Gerrit as a git remote for your Impala repository, do the following:
Code Block |
---|
cd ${IMPALA_HOME}
git remote add asf-gerrit ssh://<your-github-username>@gerrit.cloudera.org:29418/Impala-ASF |
...
If using HTTP to connect to Gerrit, use the following command to add the Gerrit remote is also works:
Code Block |
---|
git remote add asf-gerrit http://<your-github-username>@gerrit.cloudera.org:8080/a/Impala-ASF |
Pay attention, when using HTTP to push/pull code, we need to input username/password. Do not use login account directly, we should get username/password from "Settings→HTTP Password" instead.
Sending a patch for review
Install the Gerrit pre-commit hook
Gerrit keeps track of different patches by generating a unique Change-Id
that is constant over all iterations of a patch (obviously the Git hash won't do, since that changes every time the patch changes). That Change-Id
is appended to every commit message:
IMPALA-1726: Move JNI / Thrift utilities to separate header
To avoid pulling in jni.h in the codegen module (where it does not
compile), this patch moves the methods that depend on both Thrift and
JNI to a separate header where it can be included more precisely.
Change-Id: I4d97f1816b24149d9163dce59f31b2afe2642b11
Gerrit provides a "pre-commit hook" that automates Change-Id
generation. Installing it is very easy:
cd ${IMPALA_HOME}
curl -o .git/hooks/commit-msg https://gerrit.cloudera.org/tools/hooks/commit-msg
chmod u+x .git/hooks/commit-msg
After the hook is installed, every commit you make will get its own Change-Id
. Without it, Gerrit will reject all patches.
Rebase Your Branch
Commit all outstanding changes:
Code Block |
---|
cd $IMPALA_HOME
git add --update
git commit
|
Rebase against asf-gerrit/master (good practice to catch conflicts introduced by recent commits)
Code Block |
---|
git fetch asf-gerrit
git rebase |
...
Sending a patch for review
Install the Gerrit pre-commit hook
Gerrit keeps track of different patches by generating a unique Change-Id
that is constant over all iterations of a patch (obviously the Git hash won't do, since that changes every time the patch changes). That Change-Id
is appended to every commit message:
IMPALA-1726: Move JNI / Thrift utilities to separate header
To avoid pulling in jni.h in the codegen module (where it does not
compile), this patch moves the methods that depend on both Thrift and
JNI to a separate header where it can be included more precisely.
Change-Id: I4d97f1816b24149d9163dce59f31b2afe2642b11
Gerrit provides a "pre-commit hook" that automates Change-Id
generation. Installing it is very easy:
cd ${IMPALA_HOME}
curl -o .git/hooks/commit-msg https://gerrit.cloudera.org/tools/hooks/commit-msg
chmod u+x .git/hooks/commit-msg
After the hook is installed, every commit you make will get its own Change-Id
. Without it, Gerrit will reject all patches.
Rebase Your Branch
Commit all outstanding changes:
Code Block |
---|
cd $IMPALA_HOME
git add --update
git commit
|
Rebase against asf-gerrit/master (good practice to catch conflicts introduced by recent commits)
Code Block |
---|
git fetch asf-gerrit
git rebase asf-gerrit/master
|
You might have to resolve merge conflicts during 'git rebase'. Follow the instructions, then continue with
Code Block |
---|
git rebase --continue
|
Squash everything down to a single commit:
Code Block |
---|
git rebase -i asf-gerrit/master
|
You might have to resolve merge conflicts during 'git rebase'. Follow the instructions, then continue with
Code Block |
---|
git rebase --continue
|
Squash everything down to a single commit:
Code Block |
---|
git rebase -i asf-gerrit/master
|
Make sure to pick only the Make sure to pick only the first commit and 's' (squash) following lines, then edit the commit message into something coherent. Run the git log command to see that you're exactly one commit ahead of asf-gerrit/master
...
To send a patch for review, you should push it to a Gerrit-specific 'branch' on the Gerrit remote. That branch has the form form refs/for/<branch-name>
. That patch will then be visible to code reviewers, who will review your code before it becomes part of Impala. If you want to see what a patch looks like without making it visible to code reviewers, push to the branch refs/drafts/<branch-name>. For the vast majority of patches the target branch will be master, which is where all mainline development happens. During releases, release managers may push commits to a specific release branch, however most new development will happen on master
.
One thing to note is that Gerrit will send all patches between the HEAD
of the target branch and your current branch's HEAD
for review. So:
...
In the example below, we're pushing HEAD to be a draft change. Gerrit provides a URL for the review.
Code Block |
---|
$ git push asf-gerrit HEAD:refs/ |
...
drafts/master |
...
Counting objects: 3, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 332 bytes | 0 bytes/s, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2)
remote: Processing changes: new: 1, refs: 1, done
remote:
remote: New Changes:
remote: http://gerrit.cloudera.org:8080/8335 test [DRAFT]
remote:
To ssh://XXXX@gerrit.cloudera.org:29418/Impala-ASF |
Visit the URL that Gerrit provided to review the diff before sending it out to reviewers. Check that you've uploaded the right commit and that you've included what you wanted in the diff. When you've reviewed it yourself, hit the "Publish" button () to send the review to the community. This will make the review visible, but it won't be an official part of the Impala code base yet.
Note that Gerrit will send all patches between the HEAD
of the target branch and your current branch's HEAD
for review. Please therefore make certain that you are only pushing the commits you want reviewed: every separate commit translates to an e-mail in everyone's inbox!
Verifying a patch (open to all Impala contributors)
Note |
---|
The following does not apply if changes are only within the |
The following Jenkins jobs are available to all Impala contributors for testing patches they submit to Gerrit.
- pre-review-test: Use this to compile Impala and run, if desired, tests or test subsets.
bin/run-all-tests.sh
in the source tree is the best place to understand the meanings to the options of this job. - gerrit-verify-dryrun-external (new September 2017): Use this to run the full set of verifications, including multiple compilations of Impala using various build tools, and execution of all backend tests, frontend tests, core end-to-end tests, and Apache RAT verification. This is a wrapper around what a committer will ultimately run for you to verify and submit your patch (gerrit-verify-dryrun).
Neither of these jobs write a comment or Verified bit or attempt to Submit a Gerrit patch set. A submitter ought to monitor his or her job as it progresses. A submitter is encouraged to manually link a successful job in a Gerrit review comment as demonstration of success. When testing a draft, the "Impala Public Jenkins" user needs to be added to the change, so that Jenkins can access it
... will push all commits between asf-gerrit/master
and your HEAD
. Please therefore make certain that you are only pushing the commits you want reviewed: every separate commit translates to an e-mail in everyone's inbox!
Testing your configuration
If you want to check that you set up gerrit correctly, you can
Code Block |
---|
git push --no-thin asf-gerrit HEAD:refs/drafts/master |
This will push a patch that only you can see. When you see it has worked, you can click "Abandon" on it in the web interface.
Verifying and submitting a patch (Impala committers only
...
)
Once a change has a +2 from a committer and no -1 from any committer, it is ready to be verified and merged to gerrit. Remember that the source of truth for what is in Impala is the official Apache git server. Gerrit serves as a staging ground for reviewing patches, and once a patch is approved, a sort of waiting room while patches wait for a committer to officially move them to the Apache git repo.
To verify a patch, we use one of two different automated processes. Both are restricted to use by committers. If you are not a committer and your patch has been +2ed, please ask a committer to run the verification for you.
First, log in to httpto https://jenkins.impala.io:8080. If you are a committer and forgot your password, ask dev@impala.apache.org for help. Someone will reset your password.
Then, if your commit changes only files in the docs/ folder:
- Go to httphttps://jenkins.impala.io:8080/job/gerrit-docs-submit/build?delay=0sec. Put your gerrit patch URL in the PATCH_URL field. Leave the other fields with their default values. Press "Build".
- If all goes well, you will see messages like "Build started: httphttps://jenkins.impala.io:8080/job/gerrit-docs-submit/4/" and "Verified+1" and "Change has been successfully cherry-picked as 84ee40428dbb18146760adec8c5a03559f527ddb by Impala Public Jenkins" on your patch.
- If something breaks, go to the URL Jenkins posted to your patch. It will look something like this: httphttps://jenkins.impala.io:8080/job/gerrit-docs-submit/10/. Click on the "Build Artifact" and "Console Output" to look at the logs and figure out what went wrong.
If your commit doesn't change any files in the docs/ folder:
- Go to httphttps://jenkins.impala.io:8080/job/gerrit-verify-dryrun/build?delay=0sec. Put your gerrit patch URL in the PATCH_URL field. Leave the other fields with their default values. Press "Build".
- If all goes well, you will see messages like "Build started: httphttps://jenkins.impala.io:8080/job/gerrit-verify-dryrun/151/" and "Verified+1" and "Change has been successfully cherry-picked as 84ee40428dbb18146760adec8c5a03559f527ddb by Impala Public Jenkins" on your patch.
- If something breaks, go to the URL Jenkins posted to your patch. It will look something like this: httphttps://jenkins.impala.io:8080/view/Gerrit/job/gerrit-verify-dryrun/141/. Click on the "Build Artifact" and "Console Output" to look at the logs and figure out what went wrong.
If your commit touches files both in and out of the docs/ folder, run httphttps://jenkins.impala.io:8080/job/gerrit-verify-dryrun/build?delay=0sec first, following the directions above. Once it succeeds, run httphttps://jenkins.impala.io:8080/job/gerrit-docs-submit/build?delay=0sec.
Tip |
---|
Verifying and cherry-picking a patch can be simplified with a bookmarklet. Here is how to do that in Chrome:
By changing the javascript URL, you can also make a bookmarklet for the docs Jenkins job. |
...
Code Block |
---|
bin/push_to_asf.py |
push_to_asf.py checks the latest commits in gerrit and checks if they are in the Apache git repo. If some are not in the Apache git repo yet, it will ask you if you want to update the Apache git repo with the missing commits found in the Gerrit repo. It does not check what your local state is at all. It only compares remote Gerrit with the remote Apache repo. Keep in mind that if you are a committer, it will allow you to commit any change authored by anyone that has passed the Jenkins cherry-picking described above.
Creating a branch (Impala committers only
...
)
According to project bylaws, branch creation is by lazy consensus of the PMC. We recommend that you email the dev mailing list to let people know about your branch so they understand its purpose.
...