| commit | author | age | ||
| 49f5c4 | 1 | Hacking on Pyramid |
| CM | 2 | ================== |
| 3 | ||
| 93b6cd | 4 | Here are some guidelines for hacking on Pyramid. |
| 49f5c4 | 5 | |
| 051e27 | 6 | Using a Development Checkout |
| CM | 7 | ---------------------------- |
| 8 | ||
| a767d8 | 9 | You'll have to create a development environment to hack on Pyramid, using a |
| 93b6cd | 10 | Pyramid checkout. You can either do this by hand, or if you have ``tox`` |
| SP | 11 | installed (it's on PyPI), you can use tox to set up a working development |
| 995155 | 12 | environment. Each installation method is described below. |
| CM | 13 | |
| 14 | By Hand | |
| 15 | +++++++ | |
| 16 | ||
| 93b6cd | 17 | - While logged into your GitHub account, navigate to the Pyramid repo on |
| SP | 18 | GitHub. |
| 19 | ||
| 20 | https://github.com/Pylons/pyramid | |
| 21 | ||
| 22 | - Fork and clone the Pyramid repository to your GitHub account by clicking | |
| 23 | the "Fork" button. | |
| 24 | ||
| 25 | - Clone your fork of Pyramid from your GitHub account to your local computer, | |
| 26 | substituting your account username and specifying the destination as | |
| 27 | "hack-on-pyramid". | |
| 995155 | 28 | |
| CM | 29 | $ cd ~ |
| 93b6cd | 30 | $ git clone git@github.com:USERNAME/pyramid.git hack-on-pyramid |
| 995155 | 31 | $ cd hack-on-pyramid |
| 93b6cd | 32 | # Configure remotes such that you can pull changes from the Pyramid |
| SP | 33 | # repository into your local repository. |
| 39c7e4 | 34 | $ git remote add upstream https://github.com/Pylons/pyramid.git |
| 93b6cd | 35 | # fetch and merge changes from upstream into master |
| SP | 36 | $ git fetch upstream |
| 37 | $ git merge upstream/master | |
| 995155 | 38 | |
| 93b6cd | 39 | Now your local repo is set up such that you will push changes to your GitHub |
| SP | 40 | repo, from which you can submit a pull request. |
| 41 | ||
| 42 | - Create a virtualenv in which to install Pyramid: | |
| 995155 | 43 | |
| CM | 44 | $ cd ~/hack-on-pyramid |
| 45 | $ virtualenv -ppython2.7 env | |
| 46 | ||
| a767d8 | 47 | Note that very old versions of virtualenv (virtualenv versions below, say, |
| 995155 | 48 | 1.10 or thereabouts) require you to pass a ``--no-site-packages`` flag to |
| 41ce5c | 49 | get a completely isolated environment. |
| 995155 | 50 | |
| a767d8 | 51 | You can choose which Python version you want to use by passing a ``-p`` |
| 995155 | 52 | flag to ``virtualenv``. For example, ``virtualenv -ppython2.7`` |
| CM | 53 | chooses the Python 2.7 interpreter to be installed. |
| 54 | ||
| a767d8 | 55 | From here on in within these instructions, the ``~/hack-on-pyramid/env`` |
| 995155 | 56 | virtual environment you created above will be referred to as ``$VENV``. |
| CM | 57 | To use the instructions in the steps that follow literally, use the |
| 58 | ``export VENV=~/hack-on-pyramid/env`` command. | |
| 59 | ||
| 60 | - Install ``setuptools-git`` into the virtualenv (for good measure, as we're | |
| 93b6cd | 61 | using git to do version control): |
| 995155 | 62 | |
| CM | 63 | $ $VENV/bin/easy_install setuptools-git |
| 64 | ||
| 65 | - Install Pyramid from the checkout into the virtualenv using ``setup.py | |
| 66 | dev``. ``setup.py dev`` is an alias for "setup.py develop" which also | |
| 67 | installs testing requirements such as nose and coverage. Running | |
| 68 | ``setup.py dev`` *must* be done while the current working directory is the | |
| 93b6cd | 69 | ``pyramid`` checkout directory: |
| 995155 | 70 | |
| CM | 71 | $ cd ~/hack-on-pyramid |
| 72 | $ $VENV/bin/python setup.py dev | |
| 73 | ||
| 93b6cd | 74 | - Optionally create a new Pyramid project using ``pcreate``: |
| 995155 | 75 | |
| CM | 76 | $ cd $VENV |
| 77 | $ bin/pcreate -s starter starter | |
| 78 | ||
| 93b6cd | 79 | - ...and install the new project (also using ``setup.py develop``) into the |
| SP | 80 | virtualenv: |
| 995155 | 81 | |
| CM | 82 | $ cd $VENV/starter |
| 83 | $ $VENV/bin/python setup.py develop | |
| 84 | ||
| 85 | Using Tox | |
| 86 | +++++++++ | |
| 87 | ||
| 88 | Alternatively, if you already have ``tox`` installed, there is an easier | |
| 89 | way to get going. | |
| 051e27 | 90 | |
| 93b6cd | 91 | - Create a new directory somewhere and ``cd`` to it: |
| 051e27 | 92 | |
| 995155 | 93 | $ mkdir ~/hack-on-pyramid |
| CM | 94 | $ cd ~/hack-on-pyramid |
| 051e27 | 95 | |
| 93b6cd | 96 | - Check out a read-only copy of the Pyramid source: |
| 051e27 | 97 | |
| 995155 | 98 | $ git clone git://github.com/Pylons/pyramid.git . |
| 051e27 | 99 | |
| CM | 100 | (alternately, create a writeable fork on GitHub and check that out). |
| 101 | ||
| d53fd2 | 102 | Since Pyramid is a framework and not an application, it can be |
| 93137f | 103 | convenient to work against a sample application, preferably in its own |
| AG | 104 | virtualenv. A quick way to achieve this is to (ab-)use ``tox`` |
| 105 | (http://tox.readthedocs.org/en/latest/) with a custom configuration | |
| 93b6cd | 106 | file that's part of the checkout: |
| 00a08a | 107 | |
| TL | 108 | tox -c hacking-tox.ini |
| 109 | ||
| d53fd2 | 110 | This will create a python-2.7 based virtualenv named ``env27`` (Pyramid's |
| 00a08a | 111 | ``.gitconfig` ignores all top-level folders that start with ``env`` specifically |
| TL | 112 | for this use case) and inside that a simple pyramid application named |
| 93b6cd | 113 | ``hacking`` that you can then fire up like so: |
| 00a08a | 114 | |
| TL | 115 | cd env27/hacking |
| 25d8b9 | 116 | ../bin/python setup.py develop |
| 00a08a | 117 | ../bin/pserve development.ini |
| 051e27 | 118 | |
| 49f5c4 | 119 | Adding Features |
| CM | 120 | --------------- |
| 121 | ||
| 122 | In order to add a feature to Pyramid: | |
| 4f25f4 | 123 | |
| CM | 124 | - The feature must be documented in both the API and narrative |
| 49f5c4 | 125 | documentation (in ``docs/``). |
| 4f25f4 | 126 | |
| 29ce3d | 127 | - The feature must work fully on the following CPython versions: 2.6, |
| 13b187 | 128 | 2.7, 3.2, and 3.3 on both UNIX and Windows. |
| a3ff61 | 129 | |
| CM | 130 | - The feature must work on the latest version of PyPy. |
| 4f25f4 | 131 | |
| 40b3a8 | 132 | - The feature must not cause installation or runtime failure on App Engine. |
| CM | 133 | If it doesn't cause installation or runtime failure, but doesn't actually |
| 134 | *work* on these platforms, that caveat should be spelled out in the | |
| 135 | documentation. | |
| 4f25f4 | 136 | |
| CM | 137 | - The feature must not depend on any particular persistence layer |
| 138 | (filesystem, SQL, etc). | |
| 139 | ||
| 140 | - The feature must not add unnecessary dependencies (where | |
| 141 | "unnecessary" is of course subjective, but new dependencies should | |
| 142 | be discussed). | |
| 143 | ||
| 17863d | 144 | The above requirements are relaxed for scaffolding dependencies. If a |
| CM | 145 | scaffold has an install-time dependency on something that doesn't work on a |
| 146 | particular platform, that caveat should be spelled out clearly in *its* | |
| 147 | documentation (within its ``docs/`` directory). | |
| 49f5c4 | 148 | |
| CM | 149 | Coding Style |
| 150 | ------------ | |
| 151 | ||
| 152 | - PEP8 compliance. Whitespace rules are relaxed: not necessary to put | |
| 4e0d3f | 153 | 2 newlines between classes. But 79-column lines, in particular, are |
| a767d8 | 154 | mandatory. See |
| 13b187 | 155 | http://docs.pylonsproject.org/en/latest/community/codestyle.html for more |
| CM | 156 | information. |
| 49f5c4 | 157 | |
| cdcea9 | 158 | - Please do not remove trailing whitespace. Configure your editor to reduce |
| 8a3872 | 159 | diff noise. See https://github.com/Pylons/pyramid/issues/788 for more. |
| cdcea9 | 160 | |
| a3ff61 | 161 | Running Tests |
| CM | 162 | -------------- |
| 163 | ||
| a767d8 | 164 | - To run all tests for Pyramid on a single Python version, run ``nosetests`` |
| 13b187 | 165 | from your development virtualenv (See *Using a Development Checkout* above). |
| 50f23d | 166 | |
| TL | 167 | - To run individual tests (i.e. during development) you can use a regular |
| 168 | expression with the ``-t`` parameter courtesy of the `nose-selecttests | |
| a767d8 | 169 | <https://pypi.python.org/pypi/nose-selecttests/>`_ plugin that's been |
| SP | 170 | installed (along with nose itself) via ``python setup.py dev``. The |
| 171 | easiest usage is to simply provide the verbatim name of the test you're | |
| 13b187 | 172 | working on. |
| a3ff61 | 173 | |
| CM | 174 | - To run the full set of Pyramid tests on all platforms, install ``tox`` |
| 175 | (http://codespeak.net/~hpk/tox/) into a system Python. The ``tox`` console | |
| 176 | script will be installed into the scripts location for that Python. While | |
| 177 | ``cd``'ed to the Pyramid checkout root directory (it contains ``tox.ini``), | |
| 178 | invoke the ``tox`` console script. This will read the ``tox.ini`` file and | |
| 179 | execute the tests on multiple Python versions and platforms; while it runs, | |
| 180 | it creates a virtualenv for each version/platform combination. For | |
| 93b6cd | 181 | example: |
| a3ff61 | 182 | |
| 995155 | 183 | $ sudo /usr/bin/easy_install tox |
| 98b383 | 184 | $ cd ~/hack-on-pyramid/ |
| a3ff61 | 185 | $ /usr/bin/tox |
| CM | 186 | |
| e7ad85 | 187 | - The tests can also be run using ``pytest`` (http://pytest.org/). This is |
| 7a2df2 | 188 | intended as a convenience for people who are more used or fond of ``pytest``. |
| 93b6cd | 189 | Run the tests like so: |
| 7a2df2 | 190 | |
| 852e01 | 191 | $ $VENV/bin/easy_install pytest |
| 7a2df2 | 192 | $ py.test --strict pyramid/ |
| AZ | 193 | |
| 49f5c4 | 194 | Test Coverage |
| CM | 195 | ------------- |
| 196 | ||
| a3ff61 | 197 | - The codebase *must* have 100% test statement coverage after each commit. |
| CM | 198 | You can test coverage via ``tox -e coverage``, or alternately by installing |
| cdcea9 | 199 | ``nose`` and ``coverage`` into your virtualenv (easiest via ``setup.py |
| CM | 200 | dev``) , and running ``setup.py nosetests --with-coverage``. |
| 49f5c4 | 201 | |
| c7fcdf | 202 | Documentation Coverage and Building HTML Documentation |
| CM | 203 | ------------------------------------------------------ |
| 49f5c4 | 204 | |
| c7fcdf | 205 | If you fix a bug, and the bug requires an API or behavior modification, all |
| 93b6cd | 206 | documentation in this package which references that API or behavior must be |
| SP | 207 | changed to reflect the bug fix, ideally in the same commit that fixes the bug |
| c7fcdf | 208 | or adds the feature. |
| 49f5c4 | 209 | |
| 2d045b | 210 | To build and review docs (where ``$VENV`` refers to the virtualenv you're |
| c7fcdf | 211 | using to develop Pyramid): |
| 319806 | 212 | |
| 93b6cd | 213 | 1. After following the steps above in "Using a Development Checkout", install |
| SP | 214 | Sphinx and all development requirements in your virtualenv: |
| 995155 | 215 | |
| CM | 216 | $ cd ~/hack-on-pyramid |
| 217 | $ $VENV/bin/python setup.py docs | |
| 319806 | 218 | |
| 6ef753 | 219 | 2. Update all git submodules from the top-level of your Pyramid checkout, like |
| 93b6cd | 220 | so: |
| 995155 | 221 | |
| CM | 222 | $ git submodule update --init --recursive |
| 223 | ||
| 6ef753 | 224 | This will checkout theme subrepositories and prevent error conditions when |
| JC | 225 | HTML docs are generated. |
| 226 | ||
| 93b6cd | 227 | 3. Next change into the submodule's directory and switch to a branch so that |
| SP | 228 | the submodule repositories are no longer "headless". Then update the |
| 229 | repository to ensure that we have the latest updates. | |
| 230 | See http://chrisjean.com/2009/04/20/git-submodules-adding-using-removing-and-updating/ | |
| 231 | ||
| 232 | $ cd docs/_themes | |
| 233 | $ git checkout master | |
| 234 | $ git pull | |
| 235 | ||
| 236 | 4. Change into the ``docs`` directory within your Pyramid checkout and execute | |
| 237 | the ``make`` command with some flags: | |
| 995155 | 238 | |
| CM | 239 | $ cd ~/hack-on-pyramid/pyramid/docs |
| 240 | $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build | |
| 241 | ||
| a767d8 | 242 | The ``SPHINXBUILD=...`` argument tells Sphinx to use the virtualenv Python, |
| SP | 243 | which will have both Sphinx and Pyramid (for API documentation generation) |
| 244 | installed. | |
| 319806 | 245 | |
| 93b6cd | 246 | 5. Open the ``docs/_build/html/index.html`` file to see the resulting HTML |
| c7fcdf | 247 | rendering. |
| 319806 | 248 | |
| 49f5c4 | 249 | Change Log |
| CM | 250 | ---------- |
| 251 | ||
| 252 | - Feature additions and bugfixes must be added to the ``CHANGES.txt`` | |
| 253 | file in the prevailing style. Changelog entries should be long and | |
| 254 | descriptive, not cryptic. Other developers should be able to know | |
| 255 | what your changelog entry means. | |
| 256 | ||
