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
|
``paster create``::
|
|
$ cd ../env
|
$ bin/paster create -t pyramid_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.4,
|
2.5, 2.6, and 2.7 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 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 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).
|
|
Coding Style
|
------------
|
|
- PEP8 compliance. Whitespace rules are relaxed: not necessary to put
|
2 newlines between classes. But 80-column lines, in particular, are
|
mandatory.
|
|
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).
|
|
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.
|
|
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.
|
