diff options
Diffstat (limited to 'HACKING.txt')
| -rw-r--r-- | HACKING.txt | 132 |
1 files changed, 102 insertions, 30 deletions
diff --git a/HACKING.txt b/HACKING.txt index 32381cc6c..b32a8a957 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -6,28 +6,42 @@ 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. +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 (ab)use tox to get a working development +environment. Each installation method is described below. -- Create a new directory somewhere and ``cd`` to it:: +By Hand ++++++++ - $ mkdir ~/hack-on-pyramid - $ cd ~/hack-on-pyramid +- Check out Pyramid from source:: -- Check out a read-only copy of the Pyramid source:: + $ cd ~ + $ git clone git://github.com/Pylons/pyramid.git hack-on-pyramid + $ cd hack-on-pyramid - $ git clone git://github.com/Pylons/pyramid.git +- Create a virtualenv in which to install Pyramid:: - (alternately, create a writeable fork on GitHub and check that out). + $ cd ~/hack-on-pyramid + $ virtualenv -ppython2.7 env -- Create a virtualenv in which to install Pyramid:: + 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. - $ virtualenv2.6 --no-site-packages env + 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):: - $ env/bin/easy_install setuptools-git + $ $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 @@ -35,20 +49,53 @@ checkout. ``setup.py dev`` *must* be done while the current working directory is the ``pyramid`` checkout directory:: - $ cd pyramid - $ ../env/bin/python setup.py dev + $ cd ~/hack-on-pyramid + $ $VENV/bin/python setup.py dev - At that point, you should be able to create new Pyramid projects by using ``pcreate``:: - $ cd ../env + $ cd $VENV $ bin/pcreate -s starter starter - And install those projects (also using ``setup.py develop``) into the virtualenv:: - $ cd starter - $ ../bin/python setup.py develop + $ 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 --------------- @@ -59,7 +106,7 @@ In order to add a feature to Pyramid: 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. + 2.7, 3.2, and 3.3 on both UNIX and Windows. - The feature must work on the latest version of PyPy. @@ -85,7 +132,9 @@ Coding Style - PEP8 compliance. Whitespace rules are relaxed: not necessary to put 2 newlines between classes. But 80-column lines, in particular, are - mandatory. + 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. @@ -93,9 +142,15 @@ Coding Style 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 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 @@ -106,10 +161,17 @@ Running Tests it creates a virtualenv for each version/platform combination. For example:: - $ /usr/bin/easy_install tox - $ cd ~/hack-on-pyramid/pyramid + $ 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 ------------- @@ -126,21 +188,31 @@ 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 +To build and review docs (where ``$VENV`` refers to the virtualenv you're using to develop Pyramid): -1. Run ``$yourvenv/bin/python setup.py dev docs``. This will cause Sphinx - and all development requirements to be installed in your virtualenv. +1. After following the steps above in "Using a Development Checkout", cause + Sphinx and all development requirements to be installed 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 + 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=$yourvenv/bin/sphinx-build``. The - ``SPHINXBUILD=...`` hair is there in order to tell it to use the + the ``make`` command with some flags:: + + $ cd ~/hack-on-pyramid/pyramid/docs + $ 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. |