Merge branch 'master' of github.com:Pylons/pyramid

1 files changed, 36 insertions, 6 deletions

diff --git a/HACKING.txt b/HACKING.txt
index 5b5dcc458..abfed6dab 100644
--- a/HACKING.txt
+++ b/HACKING.txt
@@ -16,13 +16,32 @@ checkout.
 
 - Check out a read-only copy of the Pyramid source::
 
-  $ git clone git://github.com/Pylons/pyramid.git
+  $ git clone git://github.com/Pylons/pyramid.git .
 
   (alternately, create a writeable fork on GitHub and check that out).
 
+Since pyramid is a framework and not an application, it can be
+convenient to work against a sample application, preferably in its
+own virtualenv. A quick way to achieve this is to (ab-)use ``tox``
+(http://codespeak.net/~hpk/tox/) with a custom configuration file that's part of
+the checkout::
+
+  tox -c hacking-tox.ini
+
+This will create a python-2.7 based virtualenv named ``env27`` (pyramid's
+``.gitconfig` ignores all top-level folders that start with ``env`` specifically
+for this use case) and inside that a simple pyramid application named
+``hacking`` that you can then fire up like so::
+
+  cd env27/hacking
+  ../bin/pserve development.ini
+
+Alternatively, if you don't want to install ``tox`` at this point,
+you an achieve the same manually by following these steps:
+
 - Create a virtualenv in which to install Pyramid::
 
-  $ virtualenv2.6 --no-site-packages env
+  $ virtualenv env
 
 - Install ``setuptools-git`` into the virtualenv (for good measure, as we're
   using git to do version control)::
@@ -93,9 +112,13 @@ Coding Style
 Running Tests
 --------------
 
-- To run tests for Pyramid on a single Python version, run ``python setup.py
-  test`` against the Python interpreter from virtualenv into which
-  you've ``setup.py develop``-ed Pyramid.
+- To run all tests for Pyramid on a single Python version, run ``nosetests`` from
+  your development virtualenv (See *Using a Development Checkout* above).
+
+- To run individual tests (i.e. during development) you can use a regular
+  expression with the ``-t`` parameter courtesy of the `nose-selecttests
+  <https://pypi.python.org/pypi/nose-selecttests/>`_ plugin that's been installed (along with nose itself) via ``python setup.py dev``. The easiest usage is to
+  simply provide the verbatim name of the test you're working on.
 
 - To run the full set of Pyramid tests on all platforms, install ``tox``
   (http://codespeak.net/~hpk/tox/) into a system Python.  The ``tox`` console
@@ -107,9 +130,16 @@ Running Tests
   example::
 
    $ /usr/bin/easy_install tox
-   $ cd ~/hack-on-pyramid/pyramid
+   $ cd ~/hack-on-pyramid/
    $ /usr/bin/tox
 
+- The tests can also be run usign ``pytest`` (http://pytest.org/).  This is
+  intended as a convenience for people who are more used or fond of ``pytest``.
+  Run the tests like so::
+
+   $ $VENV/bin/easy_install pytest
+   $ py.test --strict pyramid/
+
 Test Coverage
 -------------