Fetching contributors…
Cannot retrieve contributors at this time
159 lines (111 sloc) 5.37 KB
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
- 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://
(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 ``
dev``. `` dev`` is an alias for " develop" which also
installs testing requirements such as nose and coverage. Running
`` dev`` *must* be done while the current working directory is the
``pyramid`` checkout directory::
$ cd pyramid
$ ../env/bin/python dev
- At that point, you should be able to create new Pyramid projects by using
$ cd ../env
$ bin/pcreate -s starter starter
- And install those projects (also using `` develop``) into the
$ cd starter
$ ../bin/python 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
- 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
- Please do not remove trailing whitespace. Configure your editor to reduce
diff noise.
Running Tests
- To run tests for Pyramid on a single Python version, run ``python
test`` against the using the Python interpreter from virtualenv into which
you've `` develop``-ed Pyramid.
- To run the full set of Pyramid tests on all platforms, install ``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
$ /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 (easiest via ``
dev``) , and running `` nosetests --with-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.
To build and review docs (where ``$yourvenv`` refers to the virtualenv you're
using to develop Pyramid):
1. Run ``$yourvenv/bin/python dev docs``. This will cause Sphinx
and all development requirements to be installed in your virtualenv.
2. Update all git submodules from the top-level of your Pyramid checkout, like
git submodule update --init --recursive
This will checkout theme subrepositories and prevent error conditions when
HTML docs are generated.
3. cd to the ``docs`` directory within your Pyramid checkout and execute
``make clean html SPHINXBUILD=$yourvenv/bin/sphinx-build``. The
``SPHINXBUILD=...`` hair is there in order to tell it to use the
virtualenv Python, which will have both Sphinx and Pyramid (for API
documentation generation) installed.
4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML
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.