Add Gerrit documentation

Change-Id: I48df12b8627ef2b0c4dfedadcb90864e4a537019
Signed-off-by: Luis Pabon <lpabon@redhat.com>

1 files changed, 169 insertions, 23 deletions

diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md
index 1966d2e..49f37a7 100644
--- a/doc/markdown/dev_guide.md
+++ b/doc/markdown/dev_guide.md
@@ -1,32 +1,121 @@
 #Developer Guide
 
-##Development Environment Setup
+## Development Environment Setup
 
 The workflow for libgfapi-python is largely based upon the [Gluster-Swift Developer Guide][]  and [OpenStack Gerrit Workflow][]. Refer to those documents for setting up a Gerrit account and a complete development environment.
 
 This document focuses on setting up a quick environment for running tox tests (especially the functional tests).
 
-## Required Package Installation
-Install and start the required packages on your system to create a GlusterFS volume.
+
+### Package Requirements
+Type the following to install the required packages:
+
+* Ubuntu
+
 ```
-yum install gcc python-devel python-setuptools libffi-devel glusterfs \
-    glusterfs-server git rpm-build xfsprogs
+sudo apt-get -y install gcc python-dev python-setuptools libffi-dev \
+    git xfsprogs memcached
 ```
 
+* Fedora 19
+
+```
+sudo yum install gcc python-devel python-setuptools libffi-devel \
+    git rpm-build xfsprogs memcached
+```
+
+#### Pip installation
 Install the python pip tool by executing the following command:
 
 ```
 easy_install pip
 ```
 
-#### Tox and Nose
+### Git Setup
+If this is your first time using git, you will need to setup the
+following configuration:
+
+```
+git config --global user.name "Firstname Lastname"
+git config --global user.email "your_email@youremail.com"
+```
+
+### Download the Source
+
+The source for libgfapi-python is available in Github. To download type:
+
+```
+git clone https://github.com/gluster/libgfapi-python.git
+cd libgfapi-python
+```
+
+### Tox and Nose
 
 libgfapi-python uses tox python virtual environment for its unit and functional tests. To install tox type:
 
 ```
-pip install --upgrade tox nose
+sudo pip install --upgrade tox nose
 ```
 
+### Git Review
+The tool `git review` is a simple tool to automate interaction with Gerrit.
+It is recommended to use this tool to upload, modify, and query changes in Gerrit.
+The tool can be installed by running the following command:
+
+```
+sudo pip install --upgrade git-review
+```
+
+While many Linux distributions offer a version of `git review`,
+they do not necessarily keep it up to date. Pip provides the latest version
+of the application which avoids problems with various versions of Gerrit.
+
+You now need to setup `git review` to communicate with review.gluster.org.
+First, determine your `git review` setup by typing:
+
+```
+git review -s
+```
+
+If there is no output, then everything is setup correctly.  If the output
+contains the string *We don't know where your gerrit is*, then you need to
+setup a remote repo with the name `gerrit`.  You can inspect the current
+remote repo's by typing the following command.
+
+```
+git remote -v
+```
+
+To add the Gerrit remote repo, type the following:
+
+```
+git remote add gerrit ssh://<username>@review.gluster.org/libgfapi-python
+git remote -v
+```
+
+Now we can confirm that `git review` has been setup by typing the
+following and noticing no output is returned:
+
+```
+git review -s
+```
+
+### Workflow
+
+#### Create a topic branch
+It is recommended to create a branch in git when working on a specific topic.
+If you are currently on the *master* branch, you can type the following
+to create a topic branch:
+
+```
+git checkout -b TOPIC-BRANCH
+```
+
+where *TOPIC-BRANCH* is either bug/bug-number (e.g. bug/123456) or
+a meaningful name for the topic (e.g. feature_xyz)
+
+## Running tests
+
 ### Start services
 
 Type the following to start the glusterfs service:
@@ -41,9 +130,9 @@ Type the following to start the service automatically on system startup:
 chkconfig glusterd on
 ```
 
-## Gluster Volume Setup
+### Gluster Volume Setup
 
-### Loopback Storage Setup
+#### Loopback Storage Setup
 
 If you do not have a separate partition, please execute the following instructions to create a disk image as a file:
 
@@ -65,7 +154,7 @@ Now type the following to mount the storage:
 mount -a
 ```
 
-## Create a GlusterFS Volume
+### Create a GlusterFS Volume
 
 You now need to create a GlusterFS volume
 
@@ -75,18 +164,21 @@ gluster volume create test <hostname>:/export/brick/b1
 gluster volume start test
 ```
 
-## Download the Source
+### Important Notes:
 
-The source for libgfapi-python is available in Github. To download type:
+#### Definining a hostname
+GlusterFS does not allow for specifiyng `localhost` as a valid hostname when creating a volume, so `gfshost` was used in the functional tests. If you use a different hostname when creating the gluster volume, be sure to update the functional tests.
+
+#### Stopping services
+For the purpose of running this test, stop the `firewalld` service and disable `selinux`.
 
 ```
-git clone https://github.com/gluster/libgfapi-python.git
-cd libgfapi-python
+service firewalld stop
 ```
 
-## Running tests
+### Quality Checking
 
-### PEP8
+#### PEP8
 
 To test that the code adheres to the Python PEP8 specification, please type:
 
@@ -94,9 +186,10 @@ To test that the code adheres to the Python PEP8 specification, please type:
 tox -e pep8
 ```
 
-### Unit Tests
+#### Unit Tests
 
 Once you have made your changes, you can test the quality of the code by executing the automated unit tests as follows:
+
 ```
 tox -e ENV
 ```
@@ -106,6 +199,7 @@ where ENV is either py27 for systems with Python 2.7+, or py26 for systems with
 If new functionality has been added, it is highly recommended that one or more tests be added to the automated unit test suite. Unit tests are available under the test/unit directory.
 
 ### Functional tests
+
 The functional tests expects a `test` volume to be created and accessible.
 
 To run the functional tests, please type:
@@ -113,18 +207,70 @@ To run the functional tests, please type:
 ```
 tox -e functest
 ```
-####Important Notes:
-##### Definining a hostname
-GlusterFS does not allow for specifiyng `localhost` as a valid hostname when creating a volume, so `gfshost` was used in the functional tests. If you use a different hostname when creating the gluster volume, be sure to update the functional tests.
 
-##### Stopping services
-For the purpose of running this test, stop the `firewalld` service and disable `selinux`.
+### Commiting changes
+After making the changes needed, you can commit your changes by typing:
 
 ```
-service firewalld stop
+git commit -as
+```
+
+where the commit message should follow the following recommendations:
+
+1. The first line should be a brief message and contain less than 50
+characters.
+2. Second line blank
+3. A line, or multiple line description of the change where each line
+contains less than 70 characters.
+4. Blank line
+5. If this is a bug fix, then it should have a line as follows:
+`BUG 12345: <url to bug>`
+6. Blank line.
+
+For more information on commit messages, please visit the
+[Git Commit Messages][] page in OpenStack.org.
+
+### Uploading to Gerrit
+Once you have the changes ready for review, you can submit it to Gerrit
+by typing:
+
+```
+git review
+```
+
+After the change is reviewed, you might have to make some
+additional modifications to your change.  To continue the work for
+a specific change, you can query Gerrit for the change number by
+typing:
+
+```
+git review -l
+```
+
+Then download the change to make the new modifications by typing:
+
+```
+git review -d CHANGE_NUMBER
+```
+
+where CHANGE_NUMBER is the Gerrit change number.
+
+If you need to create a new patch for a change and include your update(s)
+to your last commit type:
+
+```
+git commit -as --amend
+```
+
+Now that you have finished updating your change, you need to re-upload
+to Gerrit using the following command:
+
+```
+git review
 ```
 
 
 [OpenStack Gerrit Workflow]: https://wiki.openstack.org/wiki/Gerrit_Workflow
 [Gerrit]: https://code.google.com/p/gerrit/
 [Gluster-Swift Developer Guide]: https://github.com/gluster/gluster-swift/blob/master/doc/markdown/dev_guide.md
+[Git Commit Messages]: https://wiki.openstack.org/wiki/GitCommitMessages