1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255
|
Hacking on Pyramid
==================
Here are some guidelines for hacking on Pyramid.
Using a Development Checkout
----------------------------
You'll have to create a development environment to hack on Pyramid, using a
Pyramid checkout. You can either do this by hand, or if you have ``tox``
installed (it's on PyPI), you can use tox to set up a working development
environment. Each installation method is described below.
By Hand
+++++++
- While logged into your GitHub account, navigate to the Pyramid repo on
GitHub.
https://github.com/Pylons/pyramid
- Fork and clone the Pyramid repository to your GitHub account by clicking
the "Fork" button.
- Clone your fork of Pyramid from your GitHub account to your local computer,
substituting your account username and specifying the destination as
"hack-on-pyramid".
$ cd ~
$ git clone git@github.com:USERNAME/pyramid.git hack-on-pyramid
$ cd hack-on-pyramid
# Configure remotes such that you can pull changes from the Pyramid
# repository into your local repository.
$ git remote add upstream git@github.com:Pylons/pyramid.git
# fetch and merge changes from upstream into master
$ git fetch upstream
$ git merge upstream/master
Now your local repo is set up such that you will push changes to your GitHub
repo, from which you can submit a pull request.
- Create a virtualenv in which to install Pyramid:
$ cd ~/hack-on-pyramid
$ virtualenv -ppython2.7 env
Note that very old versions of virtualenv (virtualenv versions below, say,
1.10 or thereabouts) require you to pass a ``--no-site-packages`` flag to
get a completely isolated environment.
You can choose which Python version you want to use by passing a ``-p``
flag to ``virtualenv``. For example, ``virtualenv -ppython2.7``
chooses the Python 2.7 interpreter to be installed.
From here on in within these instructions, the ``~/hack-on-pyramid/env``
virtual environment you created above will be referred to as ``$VENV``.
To use the instructions in the steps that follow literally, use the
``export VENV=~/hack-on-pyramid/env`` command.
- 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 ~/hack-on-pyramid
$ $VENV/bin/python setup.py dev
- Optionally create a new Pyramid project using ``pcreate``:
$ cd $VENV
$ bin/pcreate -s starter starter
- ...and install the new project (also using ``setup.py develop``) into the
virtualenv:
$ cd $VENV/starter
$ $VENV/bin/python setup.py develop
Using Tox
+++++++++
Alternatively, if you already have ``tox`` installed, there is an easier
way to get going.
- 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``
(http://tox.readthedocs.org/en/latest/) 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
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, 3.2, and 3.3 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 79-column lines, in particular, are
mandatory. See
http://docs.pylonsproject.org/en/latest/community/codestyle.html for more
information.
- 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 all tests for Pyramid on a single Python version, run ``nosetests``
from your development virtualenv (See *Using a Development Checkout* above).
- To run individual tests (i.e. during development) you can use a regular
expression with the ``-t`` parameter courtesy of the `nose-selecttests
<https://pypi.python.org/pypi/nose-selecttests/>`_ plugin that's been
installed (along with nose itself) via ``python setup.py dev``. The
easiest usage is to simply provide the verbatim name of the test you're
working on.
- 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:
$ sudo /usr/bin/easy_install tox
$ cd ~/hack-on-pyramid/
$ /usr/bin/tox
- The tests can also be run using ``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:
$ $VENV/bin/easy_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 be
changed 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. After following the steps above in "Using a Development Checkout", install
Sphinx and all development requirements in your virtualenv:
$ cd ~/hack-on-pyramid
$ $VENV/bin/python setup.py docs
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. Next change into the submodule's directory and switch to a branch so that
the submodule repositories are no longer "headless". Then update the
repository to ensure that we have the latest updates.
See http://chrisjean.com/2009/04/20/git-submodules-adding-using-removing-and-updating/
$ cd docs/_themes
$ git checkout master
$ git pull
4. Change into the ``docs`` directory within your Pyramid checkout and execute
the ``make`` command with some flags:
$ cd ~/hack-on-pyramid/pyramid/docs
$ make clean html SPHINXBUILD=$VENV/bin/sphinx-build
The ``SPHINXBUILD=...`` argument tells Sphinx to use the virtualenv Python,
which will have both Sphinx and Pyramid (for API documentation generation)
installed.
5. 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.
|