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).
|
|
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``
|
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::
|
|
$ virtualenv --no-site-packages env
|
|
- Install ``setuptools-git`` into the virtualenv (for good measure, as we're
|
using git to do version control)::
|
|
$ $VENV/bin/easy_install setuptools-git
|
|
- Install Pyramid from the checkout into the virtualenv using ``setup.py
|
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 pyramid
|
$ $VENV/bin/python setup.py dev
|
|
- At that point, you should be able to create new Pyramid projects by using
|
``pcreate``::
|
|
$ cd ../env
|
$ $VENV/bin/pcreate -s starter starter
|
|
- And install those projects (also using ``setup.py develop``) into the
|
virtualenv::
|
|
$ cd starter
|
$ $VENV/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.
|
|
- 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 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 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
|
|
- 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::
|
|
$ pip install pytest
|
$ py.test --strict pyramid/
|
|
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 ``setup.py
|
dev``) , and running ``setup.py 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 ``$VENV`` refers to the virtualenv you're
|
using to develop Pyramid):
|
|
1. Run ``$VENV/bin/python setup.py 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
|
so:
|
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=$VENV/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
|
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.
|
