Gromacs

Gerrit

    Getting started

    2) Click Register (you can choose any OpenID provider including any exisitng Google/Yahoo account. If you manually enter the URL make sure to start with http(s)://)
    3) Choose username and add an ssh key
    4) If you are a core developer write an email to Roland to get review permissions.
     
    See here for a quick intro into Gerrit.

    Setting up a local repository to work with gerrit

    Either clone using:
    $ git clone ssh://USER@gerrit.gromacs.org/gromacs.git
    
    (replace USER with your username)
    Or change the remote url using:
    $ git remote set-url origin ssh://USER@gerrit.gromacs.org/gromacs.git
    (change USER with the username you've registered)
    Or add a new remote url using:
    $ git remote add upload ssh://USER@gerrit.gromacs.org/gromacs.git
     

    Install the commit hook

    $ scp -p USER@gerrit.gromacs.org:hooks/commit-msg .git/hooks/
    (change USER with the username you've registered)

    Note: that this commit hook needs to be added to the repo where the commit will occur, not the repo where the push to upstream will occur (should they be different).

     

    Uploading a commit for review

    Make sure your HEAD is up to date (use git pull --rebase origin if someone else has committed since you last pulled), check your commit message follows the guidelines, make your commit and then use

    $ git push origin HEAD:refs/for/BRANCH
    
    (replace BRANCH with the branch it should be committed to. Currently master, release-4-5-patches, and release-4-6 of the gromacs project use gerrit. The manual project also uses gerrit).
     
    When updating/replacing an existing change, make sure the commit message has the same Change-ID. If you installed the commit hook it will have. Otherwise you have to add/correct it manually.

    Uploading a draft commit for review

    Uploading a draft lets you share a change which isn't ready yet for review for merging. It is only visible to those people you invite as reviewers, which you need to add explicitly. You upload a change as a draft by uploading it to refs/drafts/branch instead of refs/for/branch.
    Jenkins is not automatically triggered for drafts, but if you add "Jenkins Buildbot" as a reviewer, it learns that you might be interested in having it try out your code. Then, you can go to Jenkins and log in with your OpenID. Then go to  http://jenkins.gromacs.org/gerrit_manual_trigger/? and tell it search for the commit for which you want to trigger the build slaves. For example, https://gerrit.gromacs.org/#/c/1238/ is 1238 (but maybe SHA or ChangeID will work, too).

    After uploading a commit

    Use

    $ git reset --keep HEAD^
    to reset your branch to the HEAD before the commit you just uploaded. This allows you to keep your repo in sync with what every other repo thinks is the HEAD. In particular, if you have another patch to upload (or worse, have to pull in other people's patches, and then have a new patch), you probably do not want to have the second patch depend on the first one. If the first one is rejected, you have made extra work for yourself sorting out the mess. Your repo still knows about the commit, and you can cherry-pick it to somewhere if you want to use it.
     

    Reviewing someone else's uploaded commit

    The reviewing workflow is the following:

    1. https://gerrit.gromacs.org/#q,status:open,n,z shows all open changes
    2. A change needs a +2 review and a +1 verified to be allowed to be submitted. (*)
    3. A change is submitted by clicking "Submit". This should be done by the reviewer after voting +2. After a patch is submitted it is replicated to the main git server.

    Do not review your own code. The point of the policy is that at least two non-authors have voted +1, and that the issues are resolved in the opinion of the person who applies a +2 before a merge. If you have uploaded a minor fix to someone else's patch, use your judgement in whether to vote on the patch +1.

    Guide for reviewing
    • First and foremost, check correctness to the extent possible;
    • As portability and performance are the most important things (after correctness) do check for potential issues;
    • Check adherance to GROMACS coding standards;
    • We should try to ensure that commmits that implementing bugfixes (as well as important features and tasks) get a Redmine entry created and linking between the commit the Redmine entry is ensure. The linking is done automatically by Redmine if the commit message contains "keyword #issueID", the valid syntax is explaned below.
    • If the commit is a bugfix:
      • if present in Redmine it has to contain valid reference to the issue;
      • if it's a major bug, there has to be a bug report filed in Redmine  (with urgent or immediate priority) and referenced appropriately.
    • If the commit is a feature/task implementation:
      • if it's present in Redmine it has to contain valid reference to the issue;
      • Othwerwise?
     
     

    Use of Verify

    Jenkins has been installed for automated build testing. So it isn't required to vote "verify +1" anymore. But because no test suite is available yet (for most of the code) Jenkins only tests that it compiles.
     

    Further information

    Currently it is possible to review your own code. It is undesirable to review your own code, because that defeats the point. It will be deactivated if it is being abused. 
     
    For further documentation: 

    FAQ

    How do I access gerrit behind a proxy?

    If you are behind a firewall blocking port 22, you can use socat to overcome this problem by adding the following block to your ~/.ssh/config

    Host gerrit.gromacs.org
           User USER
           Hostname gerrit.gromacs.org
           ProxyCommand socat - PROXY:YOURPROXY:gerrit.gromacs.org,proxyport=PORT
    

    Replace YOURPROXY, PORT and USER, (but not PROXY!!!!) by your own seetings

    How do I link fixes with Redmine issues?

    The linking of commits that relate to an existing issue is done automatically by Redmine if the git commit message contains a reference to the Redmine entry through the issueID, the numeric ID of the respective issue (bug, feature, task). The general syntax of a git comit reference is [keyword] #issueID.

    The following two types of refereces are possible:

    • For bugfix commits one of the the[Ff]ixes[Cc]loses keywords should precede the issueID;
    • For commits related to an issue (e.g. partial implementation of feature or partial fix) no keyword is needed;
    An example commit message header:

    This commit refs #1, #2 and fixes #3

    How can I submit conflicting changes?

    When there are several, mutually conflicting changes in gerrit pending for review, the submission of the 2nd and subsequent ones will fail. Those need to be resolved locally and updated by

    $ git pull --rebase

    Then fix the conflicts and use

    $ git push
    

    Please add a comment (review without voting) saying that it was rebased with/without conflicts, to help the reviewer. 

    How do I upload an update to a pending change?

    If one wants to upload an improvement to an existing change in gerrit, one should make sure that the last commit in the log is the commit you want to improve, and it has a commit ID, and you have no unsaved work. If you don't have the commit, you can get it using the link available on the gerrit page:

    $ git reset --hard origin/BRANCH
    $ git fetch ssh://USER@gerrit.gromacs.org/gromacs refs/changes/?/?/? && git checkout FETCH_HEAD 

    (NB be sure to use "checkout" and not "cherry-pick," lest you accidentally change the base and the content in one patch. See below for more information.)

    If you made the commit in git, uploaded to gerrit and then reset your branch so that your last commit is no longer in the log, and are using the same repo, you can find the git hash from the gerrit page and get the commit back with

    $ git checkout a3e425f4

    Either way, then make your changes, add them to the index, and use

    $ git commit --amend
    $ git push origin HEAD:refs/for/BRANCH
    

    When amending the previous commit message, leave the "Change-Id" intact so that gerrit can recognize this is an update and not open a new issue.

    DO NOT rebase and update a change in one step. If both is done in one step, one cannot see the differences to the previous change (using the "Old Version History" dropdown). This makes it difficult to the reviewer because it is not clear what parts have to be re-reviewed. If you need to update and rebase your change please do it in two steps (order doesn't matter). gerrit now has a feature that allows you to rebase within gerrit, which creates the desired independent patch for that rebase (if the rebase is clean). Then you can use the result to either start work, or as a base upon which to cherry-pick or rebase other work you've already done.

    How do I get a copy of my commit for which someone else has uploaded a patch?

    Gerrit makes this easy. You can download the updated commit in various ways, and even copy a magic git command to your clipboard to use in your shell:

    You can select the kind of git operation you want to do (cherry-pick is best if you are currently in the commit that was the parent, checkout is best if you just want to get the commit and not worry about the current state of your checked out git branch) and how you want to get it. The icon on the far right will paste the magic shell command into your clipboard, for you to paste into a terminal to use.

    How do I submit lots of independent commits (e.g. bug fixes)?

    Simply pushing a whole commit tree of unrelated fixes creates dependencies between them that make for trouble when one of them needs to be changed. Instead, from an up-to-date repo, create and commit the first change (or git cherry-pick it from an existing other branch). Upload it to gerrit. Then do

    $ git reset --keep HEAD^

    This will revert to the old HEAD, and allow you to work on a new commit that will be independent of the one you've already uploaded. The one you've uploaded won't appear in the commit history until it's been reviewed and accepted on gerrit and you've pulled from the main repo, however the version of it you uploaded still exists in your repo. You can see it with git show or git checkout using its hash - which you can get from the gerrit server or by digging in the internals of your repo.

    How can I avoid needing to remember all these arcane git commands?

    In your .gitconfig, having set the git remote for the gerrit repo to upload, use something like the following to make life easier:

    [alias]
            upload-r45p = push upload HEAD:refs/for/release-4-5-patches
            upload-r46 = push upload HEAD:refs/for/release-4-6
            upload-master = push upload HEAD:refs/for/master
            upload-reset = reset --keep HEAD^
    
    
    How can I get my patch in gerrit to have a different parent?

    Sometimes, some other patch under review is a relevant point from which to start work, and you can use the canned gerrit checkouts to (say) checkout out patch 2117 and start work:

    git fetch https://gerrit.gromacs.org/gromacs refs/changes/17/2117/2 && git checkout FETCH_HEAD

    Other times you might have already uploaded a patch (e.g. patch 1 of 2145), but now see that some concurrent work makes more sense as a parent commit (e.g. patch 2 of 2117), so check it out as above, and then use the canned gerrit cherry-pick:

    git fetch https://gerrit.gromacs.org/gromacs refs/changes/45/2145/1 && git cherry-pick FETCH_HEAD
    

    Resolve any merge commits, check things look OK, and then upload. Because the ChangeId of 2145 hasn't changed, and nothing about 2117 has changed, the second patch set of 2145 will reflect the state of 2145 now having 2117 as a parent.

    This can also be useful for constructing a short development branch where the commits are somehow dependent, but should be separated for review purposes. This technique is useful when constructing a series of commits that will contribute to a release.

    How can I revert a change back to an old patchset?

    If a change accidentally gets updated or when a patchset is incorrect, you might want to revert to an older patchset. This can be done by fetching and old patchset, running git commit --amend to update the time stamp in the commit and pushing the commit back up to gerrit. Note that without the ammending you will get an error from the remote telling you that there are no new changes.

    Errors

    error: server certificate verification failed. CAfile...

    If you try to cherry-pick a change from the server, you'll probably get the error:

    $ git fetch https://gerrit.gromacs.org/p/gromacs refs/changes/09/109/1 && git cherry-pick FETCH_HEAD
    error: server certificate verification failed.
    CAfile: /etc/ssl/certs/ca-certificates.crt
    CRLfile: none while accessing https://gerrit.gromacs.org/p/gromacs/info/refs
    
    fatal: HTTP request failed
    

    As explained here, the problem is with git not trusting the certificate and as a workaround one can set globally

    $ git config --global --add http.sslVerify false
    

    or prepend GIT_SSL_NO_VERIFY=1 to the command

     

    $ GIT_SSL_NO_VERIFY=1  git fetch https://gerrit.gromacs.org/p/gromacs refs/changes/09/109/1 \
     && git cherry-pick FETCH_HEAD
    Various error messages and their meanings

    http://review.coreboot.org/Documentation/error-messages.html

    Maintenance

    Deleting Users

    Unless the user was just created and hasn't done anything in Gerrit, it is better to deactive it to make sure Gerrit doesn't have any missing references.See also https://groups.google.com/forum/?fro...ss/HBryN6LFt9A

    Deleting

    delete from accounts where account_id={id}; delete from ACCOUNT_EXTERNAL_IDS where account_id={id};

    Deactivate

    update accounts set INACTIVE='Y' , PREFERRED_EMAIL='NULL' where ACCOUNT_ID={id};delete from ACCOUNT_EXTERNAL_IDS where account_id={id};
    

    Searching for the account id:

     select full_name, PREFERRED_EMAIL, account_id from accounts;
    Page last modified 12:29, 11 Dec 2014 by rossen