diff options
Diffstat (limited to 'HACKING.txt')
| -rw-r--r-- | HACKING.txt | 68 |
1 files changed, 48 insertions, 20 deletions
diff --git a/HACKING.txt b/HACKING.txt index 0194e9bab..593e89ac1 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -29,11 +29,6 @@ checkout. $ env/bin/easy_install setuptools-git -- Install ``nose`` and ``coverage`` into the virtualenv (for running nose - tests with coverage via ``setup.py nosetests --with-coverage``):: - - $ env/bin/easy_install nose coverage - - 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):: @@ -42,10 +37,10 @@ checkout. $ ../env/bin/python setup.py develop - At that point, you should be able to create new Pyramid projects by using - ``paster create``:: + ``pcreate``:: $ cd ../env - $ bin/paster create -t pyramid_starter starter + $ bin/pcreate -s starter starter - And install those projects (also using ``setup.py develop``) into the virtualenv:: @@ -61,13 +56,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, and 3.2 on both UNIX and Windows. + +- The feature must work on the latest version of PyPy. -- 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 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,10 +73,10 @@ 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 ------------ @@ -88,12 +85,33 @@ Coding Style 2 newlines between classes. But 80-column lines, in particular, are mandatory. +Running Tests +-------------- + +- To run tests for Pyramid on a single Python version, run ``python setup.py + test`` against the using the Python interpreter from virtualenv into which + you've ``setup.py develop``-ed Pyramid. + +- 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:: + + $ /usr/bin/easy_install tox + $ cd ~/hack-on-pyramid/pyramid + $ /usr/bin/tox + 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 ``tox -e coverage``, or alternately by installing + ``nose`` and ``coverage`` into your virtualenv, and running ``setup.py + nosetests --with-coverage``. Documentation Coverage ---------------------- @@ -103,6 +121,16 @@ Documentation Coverage that API or behavior must change to reflect the bug fix, ideally in the same commit that fixes the bug or adds the feature. +- To build and review docs: + + 1. Install ``tests_require`` dependencies from Pyramid's setup.py into your + virtualenv. + + 2. From the ``docs`` directory of the Pyramid checkout run ``make html + SPHINXBUILD=/path/to/your/virtualenv/bin/sphinx-build``. + + 3. Open the _build/html/index.html file to see the resulting rendering. + Change Log ---------- |