Merge remote-tracking branch 'refs/remotes/Pylons/master'

1 files changed, 171 insertions, 51 deletions

diff --git a/HACKING.txt b/HACKING.txt
index 0194e9bab..5bbdce0c6 100644
--- a/HACKING.txt
+++ b/HACKING.txt
@@ -1,57 +1,120 @@
 Hacking on Pyramid
 ==================
 
-Here are some guidelines about hacking on Pyramid.
+Here are some guidelines for hacking on Pyramid.
 
 Using a Development Checkout
 ----------------------------
 
-Below is a quick start on creating a development environment using a Pyramid
-checkout.
+You'll have to create a development environment to hack on Pyramid, using a
+Pyramid checkout.  You can either do this by hand, or if you have ``tox``
+installed (it's on PyPI), you can use tox to set up a working development
+environment.  Each installation method is described below.
 
-- Create a new directory somewhere and ``cd`` to it::
+By Hand
++++++++
 
-  $ mkdir ~/hack-on-pyramid
-  $ cd ~/hack-on-pyramid
+- While logged into your GitHub account, navigate to the Pyramid repo on
+  GitHub.
+  
+  https://github.com/Pylons/pyramid
 
-- Check out a read-only copy of the Pyramid source::
+- Fork and clone the Pyramid repository to your GitHub account by clicking
+  the "Fork" button.
 
-  $ git clone git://github.com/Pylons/pyramid.git
+- Clone your fork of Pyramid from your GitHub account to your local computer,
+  substituting your account username and specifying the destination as
+  "hack-on-pyramid".
 
-  (alternately, create a writeable fork on GitHub and check that out).
+   $ cd ~
+   $ git clone git@github.com:USERNAME/pyramid.git hack-on-pyramid
+   $ cd hack-on-pyramid
+   # Configure remotes such that you can pull changes from the Pyramid
+   # repository into your local repository.
+   $ git remote add upstream https://github.com/Pylons/pyramid.git
+   # fetch and merge changes from upstream into master
+   $ git fetch upstream
+   $ git merge upstream/master
 
-- Create a virtualenv in which to install Pyramid::
+Now your local repo is set up such that you will push changes to your GitHub
+repo, from which you can submit a pull request.
 
-  $ virtualenv2.6 --no-site-packages env
+- Create a virtualenv in which to install Pyramid:
 
-- Install ``setuptools-git`` into the virtualenv (for good measure, as we're
-  using git to do version control)::
+   $ cd ~/hack-on-pyramid
+   $ virtualenv -ppython2.7 env
+
+  Note that very old versions of virtualenv (virtualenv versions below, say,
+  1.10 or thereabouts) require you to pass a ``--no-site-packages`` flag to
+  get a completely isolated environment.
 
-  $ env/bin/easy_install setuptools-git
+  You can choose which Python version you want to use by passing a ``-p``
+  flag to ``virtualenv``.  For example, ``virtualenv -ppython2.7``
+  chooses the Python 2.7 interpreter to be installed.
 
-- Install ``nose`` and ``coverage`` into the virtualenv (for running nose
-  tests with coverage via ``setup.py nosetests --with-coverage``)::
+  From here on in within these instructions, the ``~/hack-on-pyramid/env``
+  virtual environment you created above will be referred to as ``$VENV``.
+  To use the instructions in the steps that follow literally, use the
+  ``export VENV=~/hack-on-pyramid/env`` command.
+
+- Install ``setuptools-git`` into the virtualenv (for good measure, as we're
+  using git to do version control):
 
-  $ env/bin/easy_install nose coverage
+   $ $VENV/bin/easy_install setuptools-git
 
 - Install Pyramid from the checkout into the virtualenv using ``setup.py
-  develop`` (running ``setup.py develop`` *must* be done while the current
-  working directory is the ``pyramid`` checkout directory)::
+  dev``.  ``setup.py dev`` is an alias for "setup.py develop" which also
+  installs testing requirements such as nose and coverage.  Running
+  ``setup.py dev`` *must* be done while the current working directory is the
+  ``pyramid`` checkout directory:
+
+   $ cd ~/hack-on-pyramid
+   $ $VENV/bin/python setup.py dev
+
+- Optionally create a new Pyramid project using ``pcreate``:
+
+  $ cd $VENV
+  $ bin/pcreate -s starter starter
+
+- ...and install the new project (also using ``setup.py develop``) into the
+  virtualenv:
 
-  $ cd pyramid
-  $ ../env/bin/python setup.py develop
+  $ cd $VENV/starter
+  $ $VENV/bin/python setup.py develop
+
+Using Tox
++++++++++
+
+Alternatively, if you already have ``tox`` installed, there is an easier
+way to get going.
+
+- Create a new directory somewhere and ``cd`` to it:
+
+   $ mkdir ~/hack-on-pyramid
+   $ cd ~/hack-on-pyramid
+
+- Check out a read-only copy of the Pyramid source:
+
+   $ git clone git://github.com/Pylons/pyramid.git .
+
+  (alternately, create a writeable fork on GitHub and check that out).
 
-- At that point, you should be able to create new Pyramid projects by using
-  ``paster create``::
+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://tox.readthedocs.org/en/latest/) with a custom configuration
+file that's part of the checkout:
 
-  $ cd ../env
-  $ bin/paster create -t pyramid_starter starter
+  tox -c hacking-tox.ini
 
-- And install those projects (also using ``setup.py develop``) into the
-  virtualenv::
+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 starter
-  $ ../bin/python setup.py develop
+  cd env27/hacking
+  ../bin/python setup.py develop
+  ../bin/pserve development.ini
 
 Adding Features
 ---------------
@@ -61,13 +124,15 @@ In order to add a feature to Pyramid:
 - The feature must be documented in both the API and narrative
   documentation (in ``docs/``).
 
-- The feature must work fully on the following CPython versions: 2.4,
-  2.5, 2.6, and 2.7 on both UNIX and Windows.
+- The feature must work fully on the following CPython versions: 2.6, 2.7, 3.2,
+  3.3, 3.4, and 3.5 on both UNIX and Windows.
 
-- The feature must not cause installation or runtime failure on Jython
-  or App Engine.  If it doesn't cause installation or runtime failure,
-  but doesn't actually *work* on these platforms, that caveat should be
-  spelled out in the documentation.
+- The feature must work on the latest version of PyPy and PyPy3.
+
+- The feature must not cause installation or runtime failure on App Engine.
+  If it doesn't cause installation or runtime failure, but doesn't actually
+  *work* on these platforms, that caveat should be spelled out in the
+  documentation.
 
 - The feature must not depend on any particular persistence layer
   (filesystem, SQL, etc).
@@ -76,32 +141,88 @@ In order to add a feature to Pyramid:
   "unnecessary" is of course subjective, but new dependencies should
   be discussed).
 
-The above requirements are relaxed for paster template dependencies.
-If a paster template has an install-time dependency on something that
-doesn't work on a particular platform, that caveat should be spelled
-out clearly in *its* documentation (within its ``docs/`` directory).
+The above requirements are relaxed for scaffolding dependencies.  If a
+scaffold has an install-time dependency on something that doesn't work on a
+particular platform, that caveat should be spelled out clearly in *its*
+documentation (within its ``docs/`` directory).
 
 Coding Style
 ------------
 
 - PEP8 compliance.  Whitespace rules are relaxed: not necessary to put
-  2 newlines between classes.  But 80-column lines, in particular, are
-  mandatory.
+  2 newlines between classes.  But 79-column lines, in particular, are
+  mandatory.  See
+  http://docs.pylonsproject.org/en/latest/community/codestyle.html for more
+  information.
+
+- Please do not remove trailing whitespace.  Configure your editor to reduce
+  diff noise. See https://github.com/Pylons/pyramid/issues/788 for more.
+
+Running Tests
+--------------
+
+- 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
+  script will be installed into the scripts location for that Python.  While
+  ``cd``'ed to the Pyramid checkout root directory (it contains ``tox.ini``),
+  invoke the ``tox`` console script.  This will read the ``tox.ini`` file and
+  execute the tests on multiple Python versions and platforms; while it runs,
+  it creates a virtualenv for each version/platform combination.  For
+  example::
+
+   $ sudo /usr/bin/easy_install tox
+   $ cd ~/hack-on-pyramid/
+   $ /usr/bin/tox
+
+- The tests can also be run using ``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
+   $ $VENV/bin/py.test --strict pyramid/
+
+- Functional tests related to the "scaffolds" (starter, zodb, alchemy) which
+  create a virtualenv, install the scaffold package and its dependencies, start
+  a server, and hit a URL on the server can be run like so::
+
+   $ ./scaffoldtests.sh
+
+  Alternately::
+
+   $ tox -e{py26,py27,py32,py33,py34,py35,pypy,pypy3}-scaffolds,
 
 Test Coverage
 -------------
 
-- The codebase *must* have 100% test statement coverage after each
-  commit.  You can test coverage via ``python setup.py nosetests
-  --with-coverage`` (requires the ``nose`` and ``coverage`` packages).
+- The codebase *must* have 100% test statement coverage after each commit.  You
+  can test coverage via ``./coverage.sh`` (which itself just executes ``tox
+  -epy2-cover,py3-cover,coverage``).
 
-Documentation Coverage
-----------------------
+Documentation Coverage and Building HTML Documentation
+------------------------------------------------------
 
-- If you fix a bug, and the bug requires an API or behavior
-  modification, all documentation in this package which references
-  that API or behavior must change to reflect the bug fix, ideally in
-  the same commit that fixes the bug or adds the feature.
+If you fix a bug, and the bug requires an API or behavior modification, all
+documentation in this package which references that API or behavior must be
+changed to reflect the bug fix, ideally in the same commit that fixes the bug
+or adds the feature.  To build and review docs, use the following steps.
+
+1. In the main Pyramid checkout directory, run ``./builddocs.sh`` (which just
+   turns around and runs ``tox -e docs``)::
+
+    $ ./builddocs.sh
+
+2. Open the ``docs/_build/html/index.html`` file to see the resulting HTML
+   rendering.
 
 Change Log
 ----------
@@ -111,4 +232,3 @@ Change Log
   descriptive, not cryptic.  Other developers should be able to know
   what your changelog entry means.
 
-