Hacking on Pyramid
|
==================
|
|
Here are some guidelines about hacking on Pyramid.
|
|
Using a Development Checkout
|
----------------------------
|
|
Below is a quick start on creating a development environment using a Pyramid
|
checkout.
|
|
- 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).
|
|
- Create a virtualenv in which to install Pyramid::
|
|
$ virtualenv2.6 --no-site-packages env
|
|
- Install ``setuptools-git`` into the virtualenv (for good measure, as we're
|
using git to do version control)::
|
|
$ env/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)::
|
|
$ cd pyramid
|
$ ../env/bin/python setup.py develop
|
|
- At that point, you should be able to create new Pyramid projects by using
|
``pcreate``::
|
|
$ cd ../env
|
$ bin/pcreate -s starter starter
|
|
- And install those projects (also using ``setup.py develop``) into the
|
virtualenv::
|
|
$ cd starter
|
$ ../bin/python setup.py develop
|
|
Adding Features
|
---------------
|
|
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.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 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).
|
|
- The feature must not add unnecessary dependencies (where
|
"unnecessary" is of course subjective, but new dependencies should
|
be discussed).
|
|
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.
|
|
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 ``tox -e coverage``, or alternately by installing
|
``nose`` and ``coverage`` into your virtualenv, and running ``setup.py
|
nosetests --with-coverage``.
|
|
Documentation Coverage
|
----------------------
|
|
- 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.
|
|
- 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
|
----------
|
|
- Feature additions and bugfixes must be added to the ``CHANGES.txt``
|
file in the prevailing style. Changelog entries should be long and
|
descriptive, not cryptic. Other developers should be able to know
|
what your changelog entry means.
|
