Adding contributing page into documentation

Change-Id: Ie033d1dc087184fd77506b0149101ac26eb459ff

CONTRIBUTING.rst

@@ -1,16 +0,0 @@
-If you would like to contribute to the development of OpenStack,
-you must follow the steps in this page:
-
-   http://docs.openstack.org/infra/manual/developers.html
-
-Once those steps have been completed, changes to OpenStack
-should be submitted for review via the Gerrit tool, following
-the workflow documented at:
-
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
-
-Pull requests submitted through GitHub will be ignored.
-
-Bugs should be filed on Launchpad, not GitHub:
-
-   https://bugs.launchpad.net/vmtp

Dockerfile

@@ -1,6 +1,6 @@
 # docker file for creating a container that has vmtp installed and ready to use
 FROM ubuntu:14.04
-MAINTAINER openstack-systems-group <openstack-systems-group@cisco.com>
+MAINTAINER vmtp-core <vmtp-core@lists.launchpad.net>
 
 # Install VMTP script and dependencies
 RUN apt-get update && apt-get install -y \

README.rst

@@ -8,8 +8,7 @@ VMTP is a data path performance tool for OpenStack clouds.
 Features
 --------
 
-If you need a quick and simple way to get VM level or host level single-flow throughput and latency numbers from any OpenStack cloud, and take into account various Neutron topologies, this is the tool to use.
+If you need a quick and simple way to get VM level or host level single-flow throughput and latency numbers from any OpenStack cloud, and take into account various Neutron topologies, this is the tool to use. VMTP is a python application that will automatically perform ping connectivity, ping round trip time measurement (latency) and TCP/UDP throughput measurement for the following flows on any OpenStack deployment:
-VMTP is a python application that will automatically perform ping connectivity, ping round trip time measurement (latency) and TCP/UDP throughput measurement for the following flows on any OpenStack deployment:
 
 * VM to VM same network (private fixed IP)
 * VM to VM different network same tenant (intra-tenant L3 fixed IP)
@@ -29,8 +28,8 @@ For VM-related flows, VMTP will automatically create the necessary OpenStack res
 
 See the usage page for the description of all the command line arguments supported by VMTP.
 
-Pre-requisite to run VMTP
+Pre-requisite
--------------------------
+-------------
 
 VMTP runs on any Python 2.X envirnment (validated on Linux and MacOSX).
 
@@ -89,17 +88,20 @@ VMTP will display the results to stdout with the following data:
 
 Detailed results can also be stored in a file in JSON format using the *--json* command line argument and/or stored directly into a MongoDB server.
 
+
 Limitations and Caveats
 -----------------------
 
-VMTP only measures performance for single-flows at the socket/TCP/UDP level (in a VM or natively).
+VMTP only measures performance for single-flows at the socket/TCP/UDP level (in a VM or natively). Measured numbers therefore reflect what most applications will see.
-Measured numbers therefore reflect what most applications will see.
+
 It is not designed to measure driver level data path performance from inside a VM (such as bypassing the kernel TCP stack and write directly to virtio), there are better tools that can address this type of mesurement.
 
 
 License
 -------
+
 VMTP is licensed under Apache License 2.0.
+
 Below are the benchmark tools that are used in VMTP, and you must accept the license of each tool before using VMTP.
 
 * iperf: BSD License (https://iperf.fr/license.html)

doc/source/contributing.rst

@@ -1,4 +1,109 @@
 ============
 Contributing
 ============
-.. include:: ../../CONTRIBUTING.rst
+
+Contribute to VMTP
+------------------
+
+Below are a simplified version of the workflow to work on VMTP. For complete instructions, you have to follow the Developer's Guide in OpenStack official documents. Refer to :ref:`below section <developer_guide_of_openstack>` for links.
+
+
+Start working
+^^^^^^^^^^^^^
+
+Before starting, a GitHub/StackForge respository based installation must be done. Refer :ref:`here <git_installation>` for detailed documentation.
+
+1. From the root of your workspace, check out a new branch to work on::
+
+    $ git checkout -b <TOPIC-BRANCH>
+
+2. Happy working on your code for features or bugfixes;
+
+
+Before Commit
+^^^^^^^^^^^^^
+
+There are some criteria that are enforced to commit to VMTP. Below commands will perform the check and make sure your code complys with it.
+
+3. PEP 8::
+
+    $ tox -epep8
+
+**Note:** The first run usually takes longer, as tox will create a new virtual environment and download all dependencies. Once that is the done, further run will be very fast.
+
+4. Run the test suite::
+
+    $ tox -epython27
+
+5. If you made a documentation change (i.e. changes to .rst files), make sure the documentation is built as you expected::
+
+    $ cd <vmtp-ws-root>/doc
+    $ make html
+
+Once finished, the documentation in HTML format will be ready at <vmtp-ws-root>/doc/build/html.
+
+
+Submit Review
+^^^^^^^^^^^^^
+
+6. Commit the code::
+
+    $ git commit -a
+
+**Note:** For a feature commit, please supply a clear commit message indicating what the feature is; for a bugfix commit, please also containing a launchpad link to the bug you are working on.
+
+7. Submit the review::
+
+    $ git review
+
+The members in the VMTP team will get notified once the Jenkin verification is passed. So watch your email from the review site, as it will contain the updates for your submission.
+
+8. If the code is approved with a +2 review, Gerrit will automatically merge your code.
+
+
+File Bugs
+---------
+
+Bugs should be filed on Launchpad, not GitHub:
+
+   https://bugs.launchpad.net/vmtp
+
+
+Build VMTP Docker Image
+-----------------------
+
+Two files are used to build the Docker image: *Dockerfile* and *.dockerignore*. The former provides all the build instructions while the latter provides the list of files/directories that should not be copied to the Docker image.
+
+In order to make the Docker image clean, remove all auto generated files from the root of your workspace first. It is strongly recommeneded to simply pull a new one from GitHub/StackForge. Specify the image name and the tag, and feed them to docker build. Examples to build the image with name "$USER/vmtp", tag "2.0.0" and "latest"::
+
+    $ cd <vmtp-ws-root>
+    $ sudo docker build --tag=$USER/vmtp:2.0.0 .
+    $ sudo docker build --tag=$USER/vmtp:latest .
+
+The images should be available for use::
+
+    $ sudo docker images
+    REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
+    ahothan/vmtp        2.0.0               9f08056496d7        27 hours ago        494.6 MB
+    ahothan/vmtp        latest              9f08056496d7        27 hours ago        494.6 MB
+
+For exchanging purposes, the image could be saved to a tar archive. You can distribute the VMTP Docker image among your servers easily with this feature::
+
+    $ sudo docker save <IMAGE_ID> -o <IMAGE_FILE>
+
+
+.. _developer_guide_of_openstack:
+
+Developer's Guide of OpenStack
+------------------------------
+
+If you would like to contribute to the development of OpenStack, you must follow the steps in this page:
+
+   http://docs.openstack.org/infra/manual/developers.html
+
+Once those steps have been completed, changes to OpenStack should be submitted for review via the Gerrit tool, following the workflow documented at:
+
+   http://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+Pull requests submitted through GitHub will be ignored.
+

doc/source/index.rst

@@ -16,6 +16,7 @@ Contents:
    usage
    setup
    implementation
+   issue
    contributing
 
 .. Indices and tables

doc/source/installation.rst

@@ -21,9 +21,9 @@ Once the docker.io is installed, download the latest VMTP image from Docker Hub:
 The new image will be shown in the list::
 
     $ sudo docker images
-    REPOSITORY           TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
+    REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
-    ahothan/vmtp         1.0.3               8223008be44d        23 hours ago        515.9 MB
+    ahothan/vmtp        2.0.0               9f08056496d7        27 hours ago        494.6 MB
-    ahothan/vmtp         latest              8223008be44d        23 hours ago        515.9 MB
+    ahothan/vmtp        latest              9f08056496d7        27 hours ago        494.6 MB
 
 Alternatively, for development or test purpose, a binary image could be loaded from a filesystem as well::
 
@@ -71,11 +71,14 @@ Or from the Docker image shell::
     $ cat shared/res.json
 
 
+.. _git_installation:
+
 GitHub/StackForge Repository based Installation
 -----------------------------------------------
 
 It is recommended to run VMTP inside a virtual environment. However, it can be skipped if installed in a dedicated VM.
 
+
 Super quick installation on Ubuntu/Debian
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/source/usage.rst

@@ -133,7 +133,7 @@ VMTP requires a Linux image available in Glance to spawn VMs. It could be upload
 
 There is a candidate image defined in the default config already. It has been verified working, but of course it is OK to try other Linux distro as well.
 
-**NOTE:** Due to the limitation of the Python glanceclient API (v2.0), it is not able to create the image directly from a remote URL. So the implementation of this feature used a glance CLI command instead. Be sure to source the OpenStack rc file first before running VMTP with this feature.
+**Note:** Due to the limitation of the Python glanceclient API (v2.0), it is not able to create the image directly from a remote URL. So the implementation of this feature used a glance CLI command instead. Be sure to source the OpenStack rc file first before running VMTP with this feature.
 
 
 Quick guide to run VMTP on an OpenStack Cloud
@@ -158,10 +158,7 @@ Create one configuration file for your specific cloud and use the *-c* option to
 
 * Step 3)
 
-Upload the Linux image to the OpenStack controller node, so that OpenStack is able to spawning VMs. You will be prompted an error if the image defined in the config file is not available to use when running the tool. The image can be uploaded using either Horizon dashboard, or the command below:
+Upload the Linux image to the OpenStack controller node, so that OpenStack is able to spawning VMs. You will be prompted an error if the image defined in the config file is not available to use when running the tool. The image can be uploaded using either Horizon dashboard, or the command below::
-
-.. code::
-
     python vmtp.py -r admin-openrc.sh -p admin --vm_image_url http://<url_to_the_image>
 
 **Note:** Currently, VMTP only supports the Linux image in qcow2 format.

requirements-dev.txt

@@ -3,3 +3,4 @@ git-review>=1.24
 pylint>=1.3
 pep8>=1.5.7
 flake8>=2.3.0
+sphinx>=1.2.3