--- /dev/null
+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
+# enter an expiration time, I picked 2y for 2 years
+# enter y to accept the expiration time
+# pick O or Q to accept your name/email/comment
+# enter a pass phrase twice. it seems like backspace doesn't work, so type carefully
+gpg2 --fingerprint
+# you'll get something like this:
+# spectre:~ ckd$ gpg2 --fingerprint
+# /Users/ckd/.gnupg/pubring.gpg
+# -----------------------------
+# pub 4096R/F566C9B1 2015-04-06 [expires: 2017-04-05]
+# Key fingerprint = 7C37 02AC D651 1FA7 9209 48D3 5DD5 0C4B F566 C9B1
+# uid [ultimate] Colin Dixon <colin at colindixon.com>
+# 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 $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
\ No newline at end of file
Here is more information on `Gerrit <https://code.google.com/p/gerrit/>`_
+Prerequisites
+=============
+
+Before you get started, you should have:
+
+* an LFID account (sign up `here
+ <https://identity.linuxfoundation.org/>`_)
+* 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 LFID account.
+
+* an ssh public/private key pair (see the good `GitHub docs on generating ssh keys
+ <https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/>`_)
+
+ * register in the Gerrit server. See below for detailed instructions.
+ :ref:`register-key-gerrit`
+
+* git-review installed (see: https://www.mediawiki.org/wiki/Gerrit/git-review#Installation)
+
Clone the code
==============
Your public key is now available as **.ssh/id\_rsa.pub** in your home
folder.
+.. _register-key-gerrit:
+
Register your SSH key with Gerrit
---------------------------------
git review -v -s
+Signing Gerrit Commits
+======================
+
+1. Generate your GPG key.
+
+ The following instructions work on a Mac, but the general approach
+ should be the same on other OSes.
+
+ .. literalinclude:: _static/gpg-setup.example
+
+ If you are collaborating in keysigning, then send the output of
+ ``gpg2 --fingerprint $KEY_ID`` to your coworkers.
+
+ .. code-block:: bash
+
+ 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
+ # uid [ultimate] Colin Dixon <colin at colindixon.com>
+ # sub 4096R/DC1497E1 2015-04-06 [expires: 2017-04-05]
+
+2. Install gpg, instead of or addition to gpg2.
+
+ .. 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.
+
+3. Add you GPG to Gerrit
+
+ a. Run the following at the CLI:
+
+ .. code-block:: bash
+
+ gpg --export -a $FINGER_PRINT
+ # e.g., gpg --export -a F566C9B1
+ # in my case the output looked like:
+ # -----BEGIN PGP PUBLIC KEY BLOCK-----
+ # Version: GnuPG v2
+ #
+ # mQINBFUisGABEAC/DkcjNUhxQkRLdfbfdlq9NlfDusWri0cXLVz4YN1cTUTF5HiW
+ # ...
+ # gJT+FwDvCGgaE+JGlmXgjv0WSd4f9cNXkgYqfb6mpji0F3TF2HXXiVPqbwJ1V3I2
+ # NA+l+/koCW0aMReK
+ # =A/ql
+ # -----END PGP PUBLIC KEY BLOCK-----
+
+ b. Browse to https://git.opendaylight.org/gerrit/#/settings/gpg-keys
+ c. Click Add Key...
+ d. Copy the output from the above command, paste it into the box,
+ and click Add
+
+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 $FINGER_PRINT
+ # e.g., git config user.signingkey F566C9B1
+
+ .. note::
+
+ We can create a signed commit with ``git commit -S`` and
+ a signed push with ``git push --signed`` on the CLI instead of
+ configuring it in config if we want to manually control which commits
+ use the signature.
+
+5. Create a signed commit
+
+ a. Change a file
+ b. Create a signed commit with ``git commit -asm "test commit"``
+
+ This will result in Git asking you for your passphrase.
+ Enter it to proceed.
+
+6. Push to Gerrit with a signed-push with ``git review``
+
+ This will result in Git asking you for your passphrase.
+ Enter it to proceed.
+
+ .. note::
+
+ The signing a commit or pushing again with a signed push is not
+ recognized as a "change" by Gerrit, so if you forget to do either, you
+ need to change something about the commit to get Gerrit to accept the
+ patch again. Slightly tweaking the commit message is a good way.
+
+ .. note::
+
+ This assumes you have git review set up and push.gpgsign
+ set to true. Otherwise:
+
+ ``git push --signed gerrit HEAD:refs/for/master``
+
+ This assumes the gerrit remote is available, if not, configure
+ something like: ``ssh://ckd@git.opendaylight.org:29418/<repo>.git``
+ where repo is something like docs or controller
+
+6. Verify the signature
+
+ To do this, navigate to Gerrit and check for a green check next to your name in the patch.
+
+ .. figure:: _static/gerrit-signed-push.png
+
+ Example signed push to Gerrit.
+
Appendix
========
Code Review / releng / docs.git / commitdiff
