| commit | author | age | ||
| 49f5c4 | 1 | Hacking on Pyramid |
| CM | 2 | ================== |
| 3 | ||
| 4 | Here are some guidelines about hacking on Pyramid. | |
| 5 | ||
| 051e27 | 6 | Using a Development Checkout |
| CM | 7 | ---------------------------- |
| 8 | ||
| 9 | Below is a quick start on creating a development environment using a Pyramid | |
| 10 | checkout. | |
| 11 | ||
| 12 | - Create a new directory somewhere and ``cd`` to it:: | |
| 13 | ||
| 14 | $ mkdir ~/hack-on-pyramid | |
| 15 | $ cd ~/hack-on-pyramid | |
| 16 | ||
| 17 | - Check out a read-only copy of the Pyramid source:: | |
| 18 | ||
| 19 | $ git clone git://github.com/Pylons/pyramid.git | |
| 20 | ||
| 21 | (alternately, create a writeable fork on GitHub and check that out). | |
| 22 | ||
| 23 | - Create a virtualenv in which to install Pyramid:: | |
| 24 | ||
| 25 | $ virtualenv2.6 --no-site-packages env | |
| 26 | ||
| 27 | - Install ``setuptools-git`` into the virtualenv (for good measure, as we're | |
| 28 | using git to do version control):: | |
| 29 | ||
| 30 | $ env/bin/easy_install setuptools-git | |
| 31 | ||
| 32 | - Install Pyramid from the checkout into the virtualenv using ``setup.py | |
| cdcea9 | 33 | dev``. ``setup.py dev`` is an alias for "setup.py develop" which also |
| CM | 34 | installs testing requirements such as nose and coverage. Running |
| 35 | ``setup.py dev`` *must* be done while the current working directory is the | |
| 36 | ``pyramid`` checkout directory:: | |
| 051e27 | 37 | |
| CM | 38 | $ cd pyramid |
| cdcea9 | 39 | $ ../env/bin/python setup.py dev |
| 051e27 | 40 | |
| CM | 41 | - At that point, you should be able to create new Pyramid projects by using |
| e1ddd1 | 42 | ``pcreate``:: |
| 051e27 | 43 | |
| CM | 44 | $ cd ../env |
| e1ddd1 | 45 | $ bin/pcreate -s starter starter |
| 051e27 | 46 | |
| CM | 47 | - And install those projects (also using ``setup.py develop``) into the |
| 48 | virtualenv:: | |
| 49 | ||
| 50 | $ cd starter | |
| 51 | $ ../bin/python setup.py develop | |
| 52 | ||
| 49f5c4 | 53 | Adding Features |
| CM | 54 | --------------- |
| 55 | ||
| 56 | In order to add a feature to Pyramid: | |
| 4f25f4 | 57 | |
| CM | 58 | - The feature must be documented in both the API and narrative |
| 49f5c4 | 59 | documentation (in ``docs/``). |
| 4f25f4 | 60 | |
| 29ce3d | 61 | - The feature must work fully on the following CPython versions: 2.6, |
| a3ff61 | 62 | 2.7, and 3.2 on both UNIX and Windows. |
| CM | 63 | |
| 64 | - The feature must work on the latest version of PyPy. | |
| 4f25f4 | 65 | |
| 40b3a8 | 66 | - The feature must not cause installation or runtime failure on App Engine. |
| CM | 67 | If it doesn't cause installation or runtime failure, but doesn't actually |
| 68 | *work* on these platforms, that caveat should be spelled out in the | |
| 69 | documentation. | |
| 4f25f4 | 70 | |
| CM | 71 | - The feature must not depend on any particular persistence layer |
| 72 | (filesystem, SQL, etc). | |
| 73 | ||
| 74 | - The feature must not add unnecessary dependencies (where | |
| 75 | "unnecessary" is of course subjective, but new dependencies should | |
| 76 | be discussed). | |
| 77 | ||
| 17863d | 78 | The above requirements are relaxed for scaffolding dependencies. If a |
| CM | 79 | scaffold has an install-time dependency on something that doesn't work on a |
| 80 | particular platform, that caveat should be spelled out clearly in *its* | |
| 81 | documentation (within its ``docs/`` directory). | |
| 49f5c4 | 82 | |
| CM | 83 | Coding Style |
| 84 | ------------ | |
| 85 | ||
| 86 | - PEP8 compliance. Whitespace rules are relaxed: not necessary to put | |
| 87 | 2 newlines between classes. But 80-column lines, in particular, are | |
| 88 | mandatory. | |
| 89 | ||
| cdcea9 | 90 | - Please do not remove trailing whitespace. Configure your editor to reduce |
| CM | 91 | diff noise. |
| 92 | ||
| a3ff61 | 93 | Running Tests |
| CM | 94 | -------------- |
| 95 | ||
| 96 | - To run tests for Pyramid on a single Python version, run ``python setup.py | |
| 97 | test`` against the using the Python interpreter from virtualenv into which | |
| 98 | you've ``setup.py develop``-ed Pyramid. | |
| 99 | ||
| 100 | - To run the full set of Pyramid tests on all platforms, install ``tox`` | |
| 101 | (http://codespeak.net/~hpk/tox/) into a system Python. The ``tox`` console | |
| 102 | script will be installed into the scripts location for that Python. While | |
| 103 | ``cd``'ed to the Pyramid checkout root directory (it contains ``tox.ini``), | |
| 104 | invoke the ``tox`` console script. This will read the ``tox.ini`` file and | |
| 105 | execute the tests on multiple Python versions and platforms; while it runs, | |
| 106 | it creates a virtualenv for each version/platform combination. For | |
| 107 | example:: | |
| 108 | ||
| 109 | $ /usr/bin/easy_install tox | |
| 110 | $ cd ~/hack-on-pyramid/pyramid | |
| 111 | $ /usr/bin/tox | |
| 112 | ||
| 49f5c4 | 113 | Test Coverage |
| CM | 114 | ------------- |
| 115 | ||
| a3ff61 | 116 | - The codebase *must* have 100% test statement coverage after each commit. |
| CM | 117 | You can test coverage via ``tox -e coverage``, or alternately by installing |
| cdcea9 | 118 | ``nose`` and ``coverage`` into your virtualenv (easiest via ``setup.py |
| CM | 119 | dev``) , and running ``setup.py nosetests --with-coverage``. |
| 49f5c4 | 120 | |
| c7fcdf | 121 | Documentation Coverage and Building HTML Documentation |
| CM | 122 | ------------------------------------------------------ |
| 49f5c4 | 123 | |
| c7fcdf | 124 | If you fix a bug, and the bug requires an API or behavior modification, all |
| CM | 125 | documentation in this package which references that API or behavior must |
| 126 | change to reflect the bug fix, ideally in the same commit that fixes the bug | |
| 127 | or adds the feature. | |
| 49f5c4 | 128 | |
| c7fcdf | 129 | To build and review docs (where ``$yourvenv`` refers to the virtualenv you're |
| CM | 130 | using to develop Pyramid): |
| 319806 | 131 | |
| c7fcdf | 132 | 1. Run ``$yourvenv/bin/python setup.py dev docs``. This will cause Sphinx |
| CM | 133 | and all development requirements to be installed in your virtualenv. |
| 319806 | 134 | |
| 6ef753 | 135 | 2. Update all git submodules from the top-level of your Pyramid checkout, like |
| JC | 136 | so: |
| 137 | git submodule update --init --recursive | |
| 138 | This will checkout theme subrepositories and prevent error conditions when | |
| 139 | HTML docs are generated. | |
| 140 | ||
| 141 | 3. cd to the ``docs`` directory within your Pyramid checkout and execute | |
| c7fcdf | 142 | ``make clean html SPHINXBUILD=$yourvenv/bin/sphinx-build``. The |
| CM | 143 | ``SPHINXBUILD=...`` hair is there in order to tell it to use the |
| 144 | virtualenv Python, which will have both Sphinx and Pyramid (for API | |
| 145 | documentation generation) installed. | |
| 319806 | 146 | |
| 6ef753 | 147 | 4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML |
| c7fcdf | 148 | rendering. |
| 319806 | 149 | |
| 49f5c4 | 150 | Change Log |
| CM | 151 | ---------- |
| 152 | ||
| 153 | - Feature additions and bugfixes must be added to the ``CHANGES.txt`` | |
| 154 | file in the prevailing style. Changelog entries should be long and | |
| 155 | descriptive, not cryptic. Other developers should be able to know | |
| 156 | what your changelog entry means. | |
| 157 | ||
| 158 | ||
