Extend contributing guide

Add information on setting up development environment, running tests and
generating documentation.

Also update .gitignore to list files that will be generated during
testing.

Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com>

.gitignore

@@ -1,5 +1,6 @@
 *.py[co]
 *~
+*.egg-info
 MANIFEST
 build/*
 dist/*
@@ -7,3 +8,5 @@ doc/_build
 noarch/*
 tests/data/repo
 tests/data/repo-krb5-lookaside
+tests/_composes
+htmlcov/

doc/contributing.rst

@@ -3,6 +3,63 @@ Contributing to Pungi
 =====================
 
 
+Set up development environment
+==============================
+
+In order to work on *Pungi*, you should install *Fedora 23*. These packages
+will have to installed:
+
+ * createrepo
+ * createrepo_c
+ * cvs
+ * genisoimage
+ * gettext
+ * git
+ * isomd5sum
+ * jigdo
+ * kobo
+ * kobo-rpmlib
+ * koji
+ * libselinux-python
+ * lorax
+ * python-kickstart
+ * python-lockfile
+ * python-lxml
+ * python-productmd
+ * repoview
+ * syslinux
+ * yum
+ * yum-utils
+
+For running unit tests, these packages are recommended as well:
+
+ * python-mock
+ * python-nose
+ * python-nose-cov
+
+Technically, it is possible to work on *Fedora 22*, but setting it up is a
+major headache. Packaged version of *productmd* is too old, and *Pungi* does
+not easily work with *virtualenv*, mostly because many of its Python
+dependencies are not available on PyPI. To get it working, you have to install
+*kobo* and *productmd* directly from Git and provide symlinks to other packages
+and files in ``$(virtualenvwrapper_get_site_packages_dir)``. You will still
+need to install all of the non-Python packages above as they are used by
+calling an executable. ::
+
+    $ ln -vs "$(deactivate && python -c 'import os, koji; print os.path.dirname(koji.__file__)')" "$(virtualenvwrapper_get_site_packages_dir)"
+    $ ln -vs "$(deactivate && python -c 'import os, rpm; print os.path.dirname(rpm.__file__)')" "$(virtualenvwrapper_get_site_packages_dir)"
+    $ ln -vs "$(deactivate && python -c 'import os, rpmUtils; print os.path.dirname(rpmUtils.__file__)')" "$(virtualenvwrapper_get_site_packages_dir)"
+    $ ln -vs "$(deactivate && python -c 'import os, yum; print os.path.dirname(yum.__file__)')" "$(virtualenvwrapper_get_site_packages_dir)"
+    $ ln -vs "$(deactivate && python -c 'import os, urlgrabber; print os.path.dirname(urlgrabber.__file__)')" "$(virtualenvwrapper_get_site_packages_dir)"
+    $ ln -vs "$(deactivate && python -c 'import os, krbV; print krbV.__file__')" "$(virtualenvwrapper_get_site_packages_dir)"
+    $ ln -vs "$(deactivate && python -c 'import os, sqlitecachec; print sqlitecachec.__file__')" "$(virtualenvwrapper_get_site_packages_dir)"
+    $ ln -vs "$(deactivate && python -c 'import os, _sqlitecache; print _sqlitecache.__file__')" "$(virtualenvwrapper_get_site_packages_dir)"
+    $ PYCURL_SSL_LIBRARY=nss pip install pycurl
+    $ pip install https://git.fedorahosted.org/cgit/kobo.git/snapshot/kobo-0.4.3.tar.gz#egg=kobo
+    $ pip install https://github.com/release-engineering/productmd/archive/master.tar.gz#egg=productmd
+    $ pip install lxml pyopenssl mock sphinx setuptools nose nose-cov
+
+
 Developing
 ==========
 
@@ -18,9 +75,10 @@ Currently the development workflow for Pungi is on master branch:
     cd pungi
     git remote add upstream git@pagure.io:pungi.git
 
-    # NOTE: This workflow assumes that you never 'git commit' directly to
+  .. note::
-    # the master branch of your fork. This will make more sense when we
+      This workflow assumes that you never ``git commit`` directly to the master
-    # cover rebasing below.
+      branch of your fork. This will make more sense when we cover rebasing
+      below.
 
 - create a topic branch based on master::
 
@@ -36,7 +94,7 @@ Currently the development workflow for Pungi is on master branch:
 
     # make changes to setup.py
     git add setup.py
-    git commit -m "added awesome feature to setup.py"
+    git commit -s -m "added awesome feature to setup.py"
 
     # now we rebase
     git checkout master
@@ -50,10 +108,14 @@ Currently the development workflow for Pungi is on master branch:
     # your topic branch
     git push origin my_topic_branch
 
+  .. note::
+      In order to for your commit to be merged, you must sign-off on it. Use
+      ``-s`` option when running ``git commit``.
+
 - Create pull request in the pagure.io web UI
 
 - For convenience, here is a bash shell function that can be placed in your
-  ~/.bashrc and called such as 'pullupstream pungi-4-devel' that will
+  ~/.bashrc and called such as ``pullupstream pungi-4-devel`` that will
   automate a large portion of the rebase steps from above::
 
     pullupstream () {
@@ -73,8 +135,31 @@ Currently the development workflow for Pungi is on master branch:
 Testing
 =======
 
-You must write unit tests for any code but trivial changes.
+You must write unit tests for any code but trivial changes. Any code without
-Any code without sufficient test coverage may not be merged.
+sufficient test coverage may not be merged.
+
+To run all existing tests, suggested method is to use *nosetests*. With
+additional options, it can generate code coverage. To make sure even tests from
+executable files are run, don't forget to use the ``--exe`` option. ::
+
+    $ nosetests --exe
+    $ nosetests --exe --with-cov --cov pungi --cov-report html
+
+    # Running single test file
+    $ nosetests --exe test_arch
+
+In the ``tests/`` directory there is a shell script ``test_compose.sh`` that
+you can use to try and create a miniature compose on dummy data. The actual
+data will be created by running ``make test-data`` in project root.
+
+This testing compose does not actually use all phases that are available, and
+there is no checking that the result is correct. It only tells you whether it
+crashed or not.
+
+.. note::
+   Even when it finishes successfully, it may print errors about
+   ``repoclosure`` on *Server-Gluster.x86_64* in *test* phase. This is not a
+   bug.
 
 
 Documenting
@@ -82,3 +167,5 @@ Documenting
 
 You must write documentation for any new features and functional changes.
 Any code without sufficient documentation may not be merged.
+
+To generate the documentation, run ``make doc`` in project root.