X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fgerrit.rst;h=f0b155548b75ea61c83bc0891083572da4d0f795;hb=fc31c1e7d1e4a498e2af7f6d989df1830553f06e;hp=8d0e7ab257991930d97701eebbb74987ff1ece4a;hpb=ccfec4d5ab1113d5acd2f758d303d6b12c550bf3;p=docs.git diff --git a/docs/gerrit.rst b/docs/gerrit.rst index 8d0e7ab25..f0b155548 100644 --- a/docs/gerrit.rst +++ b/docs/gerrit.rst @@ -2,24 +2,510 @@ Gerrit Guide ############ -How to push to Gerrit -===================== +Overview of Git and Gerrit +========================== -It is highly recommended to use ssh to push to Gerrit to push code to Gerrit. -In the event that you cannot use ssh such as corporate firewall blocking you -then falling back to pushing via https should work. +Git is an opensource distributed version control system (dvcs) written +in the C language and originally developed by Linus Torvalds and others +to manage the Linux kernel. In Git, there is no central copy of the +repository. After you have cloned the repository, you have a functioning +copy of the source code with all the branches and tagged releases, in +your local repository. -Using ssh to push to Gerrit ---------------------------- +Gerrit is an opensource web-based collaborative code review tool that +integrates with Git. It was developed at Google by Shawn Pearce. Gerrit +provides a framework for reviewing code commits before they are accepted +into the code base. Changes can be uploaded to Gerrit by any user. +However, the changes are not made a part of the project until a code +review is completed. Gerrit is also a good collaboration tool for +storing the conversations that occur around the code commits. -# TODO +The OpenDaylight source code is hosted in a repository in Git. +Developers must use Gerrit to commit code to the OpenDaylight +repository. + +.. note:: + + For more information on Git, see http://git-scm.com/. For more + information on Gerrit, see https://code.google.com/p/gerrit/. + +Prerequisites +============= + +Before you get started, you should have: + +* an OpenDaylight account (sign up `here + `_) + See `Creating an OpenDaylight Account`_ below for detailed instructions. +* git installed (see: http://www.git-scm.com/downloads) +* git configured with your name, e-mail address and editor + + .. code-block:: bash + + git config --global user.name "Firstname Lastname" + git config --global user.email "email@address.com" + git config --global core.editor "text-editor-name" + + .. note:: Your name and e-mail address (including capitalization) must match what you entered + when creating your OpenDaylight account. + +* an ssh public/private key pair (see the good `Github docs on generating ssh keys + `_) + + * that is registered the OpenDaylight Gerrit server. See `Registering your SSH key with Gerrit`_ + below for detailed instructions. + +* git-review installed (see: https://www.mediawiki.org/wiki/Gerrit/git-review#Installation) + + +Setting up Each Git Repository +============================== + +To clone a new repository: + +.. code-block:: bash + + git clone https://git.opendaylight.org/gerrit/${project_short_name} + +For example to clone the Documentation repository: + +.. code-block:: bash + + git clone https://git.opendaylight.org/gerrit/docs + + +Common Gerrit Tasks +=================== + +The following sections describe the most common Gerrit tasks you will need to complete while +working with code in OpenDaylight. + +Submitting a New Patch +---------------------- + +#. On your machine, open a shell and switch to the directory with the git repository. Assuming + you are using the docs repository: + + .. code-block:: bash + + cd docs + +#. To remove any dependencies on other files you are working on, check out the appropriate branch: + + .. code-block:: bash + + git checkout ${remote_branch_name} # will switch to the branch + + .. note:: normally, ``${remote_branch_name}`` should be master, but during a release, the + master will switch to ``stable/${release_name}``, e.g., ``stable/carbon`` at some + point. Also, if you are updating an existing release check out that branch. + + .. note:: If you see an error like``error: pathspec 'stable/carbon' did not match any file(s) + known to git.``, try this command instead: + + .. code-block:: bash + + git checkout -b ${remote_branch_name} origin/${remote_branch_name} + + .. note:: This should only be necessary once. + +#. Get a copy of the latest files from the server: + + .. code-block:: bash + + git pull # will get all the changes from the server + git reset --hard origin/${remote_branch_name} # (optional) will undo any local changes you've + # (accidentally) made to ${remote_branch_name} + +#. Create a new branch for your work: + + .. code-block:: bash + + git checkout -b ${local_branch_name} + + .. note:: Spaces are not allowed in ``${local_branch_name}``. + +#. Create new files or edit existing files, as needed. +#. Commit the files you have worked on: + + * If you've created any new files, run: + + .. code-block:: bash + + git add ${filename} + + * To commit existing files you edited, run: + + * ``git commit -as`` + * Your default terminal text editor will open. + + .. note:: The -as options instruct git to commit all of the files you have edited (``-a``) + and sign your commit request with your email address and name (``-s``). The + sign-off is to indicate that you agree with this statement:: + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + + * Add a brief description of the changes you have made to the beginning of the commit request + and then save the request. + + .. note:: Writing good git commit messages is important and relatively easy, but it's good to + familiarize yourself with general guidelines like this `How to Write a Git Commit + Message Guide `_. + + .. important:: We have linters that check for some of the style guides including that the + first line of a git commit message is 50 characters or less. So, make sure to + follow that one. + +#. Submit your files for review: + + * ``git review`` + * You will receive 2 emails from Gerrit Code Review: The first indicating that a build to + incorporate your changes has started; and the second indicating whether the build was created + successfully. + +#. Determine your patch’s change number: + + * Open either of the emails you received after submitting your files for review. + * Locate the following line in the terminal: ``To view, visit `` + + .. note:: The number at the end of this URL is your patch’s change number. You will need + this in order to make updates to the patch later. + +Updating an Existing Patch +-------------------------- + +#. On your machine, open a shell and switch to the directory containing the repository: + ``cd ${repository_name}``, e.g., ``cd docs`` +#. Download the patch you want to update: ``git review -d ${change_number}`` +#. | (Optional) View information on the latest changes made to that patch: + | To view the files that were edited, run ``git show`` + | To view a listing of the files that were edited and the number of lines in those files that + were edited, run ``git show --stat`` +#. Make the necessary changes to the patch’s files. +#. Commit your changes: + + #. run ``git commit -a --amend`` + #. Update the current patch description and then save the commit request. + + .. note:: If you feel as though you did enough additional work on the patch that you should + be mentioned, add your name in the footer with a line like ``Co-Authored-By: First + Last ``. + +#. | Submit your files for review: + | ``git review`` + +You will receive 2 emails from Gerrit Code Review: the first indicating that a build to incorporate +your changes has started; and the second indicating whether the build was created successfully. + +Code Review +=========== + +All contributions to OpenDaylight Git repositories use Gerrit for code review. + +The code review process is meant to provide constructive feedback about a proposed change. +Committers and interested contributors will review the change, give their feedback, propose +revisions and work with the change author through iterations of the patch until it's ready to be +merged. + +Feedback is provided and the change is managed via the Gerrit web UI. + +.. figure:: images/gerrit-web-ui.png + + Wide view of a change via the Gerrit web UI + +Pre-review +---------- + +Many times, change authors will want to push changes to Gerrit before they are actually ready for +review. This is a good practice and is encouraged. It has been the experience of Integration/* so +far that pushing early and often tends to reduce the amount of work overall. + +.. note:: This is not required and in some projects, not encouraged, but the general idea of making + sure patches are ready for review when submitted is a good one. + +.. note:: While in draft state, Gerrit triggers, e.g., verify Jenkins jobs, won't run by default. + You can trigger them despite it being a draft by adding ``jenkins-releng`` as a reviewer. + You may need to do a recheck by replying with a comment containing recheck to trigger the + jobs after adding the reviewer. + +To mark an uploaded change as not ready for attention by committers and interested contributors (in +order of preference), either mark the Gerrit a draft (by adding a ``-D`` to your ``git review`` +command), vote -1 on it yourself or modify the commit message with "WIP" ("Work in Progress"). + +Don't add committers to the Reviewers list for a change while it's in the pre-review state, as it +adds noise to their review queue. + +Review +------ + +Once an author wants a change to be reviewed, they need to take some actions to put it on the radar +of the committers. + +If the change is marked as a draft, you'll need to publish it. This can be done from the Gerrit web +UI. + +.. figure:: images/gerrit-publish-button.png + + Gerrit Web UI button to publish a draft change. + +Remove your -1 vote if you've marked it with one. If you think the patch is ready to be merged, +vote +1. If there isn't an automated job to test your change and vote +1/-1 for Verified, you'll +need to do as much testing yourself as possible and then manually vote +1 to Verified. You can +also vote +1 for Verified if you've done testing in addition to any automated tests. Describing +the testing you did or didn't do is typically helpful. + +.. figure:: images/gerrit-voting-interface.png + + Gerrit voting interface, exposed by the Reply button. + +Once the change is published and you've voted for it to be merged, add the people who need to +review/merge the change to the Gerrit Reviewers list. For Integration/Packaging, add all of our +committers (Daniel Farrell, Jamo Luhrsen, Thanh Ha) in addition to any other relevant contributors. +The auto-complete for this Gerrit UI field is somewhat flaky, but typing the full name from the +start typically works. + +.. figure:: images/gerrit-reviewers-interface.png + + Gerrit Reviewers list with Int/Pack committers added + +Reviewers will give feedback via Gerrit comments or inline against the diff. + +.. figure:: images/gerrit-inline-feedback.png + + Gerrit inline feedback about a typo + +Updated versions of the proposed change should be pushed as new patchesets to the same Gerrit, +either by the original submitter or other contributors. Amending proposed changes owned by others +while reviewing may be more efficient than documenting the problem, -1ing, waiting for the original +submitter to make the changes, re-reviewing and merging. + +Changes can be downloaded for local manipulation and then re-uploaded with updates via git-review. +See `Updating an Existing Patch`_ above. Once you have re-uploaded the patch the Gerrit web UI for +the proposed change will reflect the new patcheset. + +.. figure:: images/gerrit-patch-update-history.png + + Gerrit history showing a patch update + +Reviewers will use the diff between the last time time they gave review and the current patchset +to quickly understand updates, speeding the code review process. + +.. figure:: images/gerrit-diff-menu.png + + Gerrit diff menu + +Iterative feedback continues until consensus is reached (typically: all active reviewers +1/+2 and +no -1s, definitely no -2s), at least one committer +2s and a committer merges the change. + +.. figure:: images/gerrit-code-review-votes.png + + Gerrit code review votes + +Merge +----- + +Once a patch has gotten a +2 from a committer and they have clicked the submit button the project's +merge job should run and publish the project's artifacts to Nexus. Once this is done other projects +will be able to see the results of that patch. + +This is particularly important when merging dependent patches across multiple projects. You will +need to wait for the merge job to run on one patch before any patches in other projects depending +on it will successful verify. + +Setting up Gerrit +================= + +Creating an OpenDaylight Account +-------------------------------- + +#. Using a Google Chrome or Mozilla Firefox browser, go to + https://git.opendaylight.org/gerrit + + The main page shows existing Gerrit requests. These are patches that + have been pushed to the repository and not yet verified, reviewed, and + merged. + + .. note:: + + If you already have an OpenDaylight account, you can click **Sign + In** in the top right corner of the page and follow the instructions + to enter the OpenDaylight page. + + .. figure:: images/gerrit-sign-in.jpg + :alt: Signing in to OpenDaylight account + + Signing in to OpenDaylight account + +#. If you do not have an existing OpenDaylight account, click **Account + signup/management** on the top bar of the main Gerrit page. + + The **WS02 Identity Server** page is displayed. + + .. figure:: images/gerrit-setup.jpg + :alt: Gerrit Account signup/management link + + Gerrit Account signup/management link + +#. In the **WS02 Identity Server** page, click **Sign-up** in the left + pane. + + There is also an option to authenticate your sign in with OpenID. This + option is not described in this document. + + .. figure:: images/gerrit-sign-up.jpg + :alt: Sign-up link for Gerrit account + + Sign-up link for Gerrit account + +#. Click on the **Sign-up with User Name/Password** image on the right + pane to continue to the actual sign-up page. + + .. figure:: images/gerrit-signup-image.jpg + :alt: Sign-up with User Name/Password Image + + Sign-up with User Name/Password Image + +#. Fill out the details in the account creation form and then click + **Submit**. + + .. figure:: images/gerrit-form-details.jpg + :alt: Filling out the details + + Filling out the details + +You now have an OpenDaylight account that can be used with Gerrit to +pull the OpenDaylight code. + +Generating SSH keys for your system +----------------------------------- + +You must have SSH keys for your system to register with your Gerrit +account. The method for generating SSH keys is different for different +types of operating systems. + +The key you register with Gerrit must be identical to the one you will +use later to pull or edit the code. For example, if you have a +development VM which has a different UID login and keygen than that of +your laptop, the SSH key you generate for the VM is different from the +laptop. If you register the SSH key generated on your VM with Gerrit and +do not reuse it on your laptop when using Git on the laptop, the pull +fails. + +.. note:: + + For more information on SSH keys for Ubuntu, see + https://help.ubuntu.com/community/SSH/OpenSSH/Keys. For generating + SSH keys for Windows, see + https://help.github.com/articles/generating-ssh-keys. + +For a system running Ubuntu operating system, follow the steps below: + +#. Run the following command:: + + mkdir ~/.ssh + chmod 700 ~/.ssh + ssh-keygen -t rsa + +#. You are prompted for a location to save the keys, and a passphrase + for the keys. + + This passphrase protects your private key while it is stored on the hard + drive. You must use the passphrase to use the keys every time you need + to login to a key-based system:: + + Generating public/private rsa key pair. + Enter file in which to save the key (/home/b/.ssh/id_rsa): + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in /home/b/.ssh/id_rsa. + Your public key has been saved in /home/b/.ssh/id_rsa.pub. + +Your public key is now available as **.ssh/id\_rsa.pub** in your home +folder. + +Registering your SSH key with Gerrit +------------------------------------ + +#. Using a Google Chrome or Mozilla Firefox browser, go to + https://git.opendaylight.org/gerrit. + +#. Click **Sign In** to access the OpenDaylight repository. + + .. figure:: images/gerrit-sign-in.jpg + :alt: Signin in to OpenDaylight repository + + Signin in to OpenDaylight repository + +#. Click your name in the top right corner of the window and then click + **Settings**. + + The **Settings** page is displayed. + + .. figure:: images/gerrit-settings.jpg + :alt: Settings page for your Gerrit account + + Settings page for your Gerrit account + +#. Click **SSH Public Keys** under **Settings**. + +#. Click **Add Key**. + +#. In the **Add SSH Public Key** text box, paste the contents of your + **id\_rsa.pub** file and then click **Add**. + + .. figure:: images/gerrit-ssh-keys.jpg + :alt: Adding your SSH key + + Adding your SSH key + +To verify your SSH key is working correctly, try using an SSH client to +connect to Gerrit’s SSHD port:: + + $ ssh -p 29418 @git.opendaylight.org + Enter passphrase for key '/home/cisco/.ssh/id_rsa': + **** Welcome to Gerrit Code Review **** + Hi , you have successfully connected over SSH. + Unfortunately, interactive shells are disabled. + To clone a hosted Git repository, use: git clone ssh://@git.opendaylight.org:29418/REPOSITORY_NAME.git + Connection to git.opendaylight.org closed. + +You can now proceed to either Pulling, Hacking, and Pushing the Code +from the CLI or Pulling, Hacking, and Pushing the Code from Eclipse +depending on your implementation. Using https to push to Gerrit ------------------------------ +============================= + +It is highly recommended to use ssh to push to Gerrit. In the event that you cannot use ssh, e.g., +a corporate firewall is blocking blocking you, then falling back to pushing via https should work. Gerrit does not allow you to use your regular account credentials when pushing -via https. Instead it requires you to first generate a http password via the -Web U and use that as the password when pushing via https. +via https. Instead it requires you to first generate a http password via the Gerrit +Web UI and use that as the password when pushing via https. .. figure:: images/gerrit-https-password-setup.png @@ -27,12 +513,21 @@ Web U and use that as the password when pushing via https. To do this: -1. navigate to https://git.opendaylight.org/gerrit/#/settings/http-password +#. navigate to https://git.opendaylight.org/gerrit/#/settings/http-password (Steps 1, 2 and 3 in the image above.) -2. click the **Generate Password** button. +#. click the **Generate Password** button. Gerrit will then generate a random password which you will need to use as your -password when using git to push code to Gerrit via https. +password when using Git to push code to Gerrit via https. + +To push using git over https, do the following + +.. code-block:: bash + + git remote add https https://git.opendaylight.org/gerrit/p/${repo_name} # adds an https version of the git server + git push https HEAD:refs/for/${branch_name} # will ask you for your username and password + # ${branch_name} should usually be master, + # but can be stable/carbon or something else Signing Gerrit Commits ====================== @@ -44,7 +539,7 @@ Signing Gerrit Commits .. code-block:: bash - brew install gpg2 # if you don't have homebrew, get that here: http://brew.sh/ + brew install gpg2 # If you don't have homebrew, get that here: http://brew.sh/ gpg2 --gen-key # pick 1 for "RSA and RSA" # enter 4096 to creat a 4096-bit key @@ -62,19 +557,19 @@ Signing Gerrit Commits # uid [ultimate] Colin Dixon # sub 4096R/DC1497E1 2015-04-06 [expires: 2017-04-05] # you're looking for the part after 4096R, which is your key ID - gpg2 --send-keys - # in the above example, the key-id would be F566C9B1 + gpg2 --send-keys $KEY_ID + # in the above example, the $KEY_ID would be F566C9B1 # you should see output like this: # gpg: sending key F566C9B1 to hkp server keys.gnupg.net If you're trying to participate in an OpenDaylight keysigning, then - send the output of ``gpg2 --fingerprint `` to + send the output of ``gpg2 --fingerprint $KEY_ID`` to keysigning@opendaylight.org .. code-block:: bash - gpg2 --fingerprint - # in the above example, the key-id would be F566C9B1 + gpg2 --fingerprint $KEY_ID + # in the above example, the $KEY_ID would be F566C9B1 # in my case, the output was: # pub 4096R/F566C9B1 2015-04-06 [expires: 2017-04-05] # Key fingerprint = 7C37 02AC D651 1FA7 9209 48D3 5DD5 0C4B F566 C9B1 @@ -85,7 +580,7 @@ Signing Gerrit Commits gpg2 has annoying things that it does when asking for your passphrase, which I haven't debugged yet. - .. note:: you can tell git to use gpg by doing: + .. note:: you can tell Git to use gpg by doing: ``git config --global gpg.program gpg2`` but that then will seem to struggle asking for your passphrase unless you have your gpg-agent set up right. @@ -96,7 +591,7 @@ Signing Gerrit Commits .. code-block:: bash - gpg --export -a + gpg --export -a $FINGER_PRINT # e.g., gpg --export -a F566C9B1 # in my case the output looked like: # -----BEGIN PGP PUBLIC KEY BLOCK----- @@ -114,13 +609,13 @@ Signing Gerrit Commits d. Copy the output from the above command, paste it into the box, and click Add -3. Set up your git to sign commits and push signatures +4. Set up your Git to sign commits and push signatures .. code-block:: bash git config commit.gpgsign true git config push.gpgsign true - git config user.signingkey + git config user.signingkey $FINGER_PRINT # e.g., git config user.signingkey F566C9B1 .. note:: you can do this instead with ``git commit -S`` @@ -128,16 +623,16 @@ Signing Gerrit Commits on the CLI instead of configuring it in config if you want to control which commits use your signature. -4. Commit and push a change +5. Commit and push a change a. change a file b. ``git commit -asm "test commit"`` - .. note:: this should result in git asking you for your passphrase + .. note:: this should result in Git asking you for your passphrase c. ``git review`` - .. note:: this should result in git asking you for your passphrase + .. note:: this should result in Git asking you for your passphrase .. note:: annoyingly, the presence of a gpgp signature or pushing of a gpg signature isn't recognized as a "change" by @@ -156,7 +651,7 @@ Signing Gerrit Commits ``ssh://ckd@git.opendaylight.org:29418/.git`` where repo is something like docs or controller -5. Verify that your commit is signed by going to the change in Gerrit +6. Verify that your commit is signed by going to the change in Gerrit and checking for a green check (instead of a blue ?) next to your name. @@ -199,8 +694,8 @@ Setting up gpg-agent on a Mac #. Restart your terminal (or log in and out) to reload the your ``.bash_profile`` or equivalent file -#. The next time a git operation makes a call to gpg, it should use +#. The next time a Git operation makes a call to gpg, it should use your gpg-agent to run a GUI window to ask for your passphrase and give you an option to save your passphrase in the keychain. - .. image:: images/pinentry-mac.png + .. figure:: images/pinentry-mac.png