| commit | author | age | ||
| 49f5c4 | 1 | Hacking on Pyramid |
| CM | 2 | ================== |
| 3 | ||
| 93b6cd | 4 | Here are some guidelines for hacking on Pyramid. |
| 49f5c4 | 5 | |
| 84b496 | 6 | |
| 051e27 | 7 | Using a Development Checkout |
| CM | 8 | ---------------------------- |
| 9 | ||
| a767d8 | 10 | You'll have to create a development environment to hack on Pyramid, using a |
| 93b6cd | 11 | Pyramid checkout. You can either do this by hand, or if you have ``tox`` |
| 84b496 | 12 | installed (it's on PyPI), you can use ``tox`` to set up a working development |
| 995155 | 13 | environment. Each installation method is described below. |
| 84b496 | 14 | |
| 995155 | 15 | |
| CM | 16 | By Hand |
| 17 | +++++++ | |
| 18 | ||
| 93b6cd | 19 | - While logged into your GitHub account, navigate to the Pyramid repo on |
| SP | 20 | GitHub. |
| 21 | ||
| 22 | https://github.com/Pylons/pyramid | |
| 23 | ||
| 24 | - Fork and clone the Pyramid repository to your GitHub account by clicking | |
| 25 | the "Fork" button. | |
| 26 | ||
| 27 | - Clone your fork of Pyramid from your GitHub account to your local computer, | |
| 28 | substituting your account username and specifying the destination as | |
| 29 | "hack-on-pyramid". | |
| 995155 | 30 | |
| 84b496 | 31 | $ cd ~ |
| SP | 32 | $ git clone git@github.com:USERNAME/pyramid.git hack-on-pyramid |
| 33 | $ cd hack-on-pyramid | |
| 34 | # Configure remotes such that you can pull changes from the Pyramid | |
| 35 | # repository into your local repository. | |
| 36 | $ git remote add upstream https://github.com/Pylons/pyramid.git | |
| 37 | # fetch and merge changes from upstream into master | |
| 38 | $ git fetch upstream | |
| 39 | $ git merge upstream/master | |
| 995155 | 40 | |
| 93b6cd | 41 | Now your local repo is set up such that you will push changes to your GitHub |
| SP | 42 | repo, from which you can submit a pull request. |
| 43 | ||
| 84b496 | 44 | - Create a virtual environment in which to install Pyramid: |
| 995155 | 45 | |
| 84b496 | 46 | $ cd ~/hack-on-pyramid |
| SP | 47 | $ python3 -m venv env |
| 995155 | 48 | |
| a767d8 | 49 | From here on in within these instructions, the ``~/hack-on-pyramid/env`` |
| 995155 | 50 | virtual environment you created above will be referred to as ``$VENV``. |
| CM | 51 | To use the instructions in the steps that follow literally, use the |
| 52 | ``export VENV=~/hack-on-pyramid/env`` command. | |
| 53 | ||
| 84b496 | 54 | - Install ``setuptools-git`` into the virtual environment (for good measure, as |
| SP | 55 | we're using git to do version control): |
| 995155 | 56 | |
| 84b496 | 57 | $ $VENV/bin/pip install setuptools-git |
| 995155 | 58 | |
| 84b496 | 59 | - Install Pyramid from the checkout into the virtual environment, where the |
| SP | 60 | current working directory is the ``pyramid`` checkout directory. We will |
| 61 | install Pyramid in editable (development) mode as well as its testing | |
| 62 | requirements. | |
| 995155 | 63 | |
| 84b496 | 64 | $ cd ~/hack-on-pyramid |
| SP | 65 | $ $VENV/bin/pip install -e ".[testing,docs]" |
| 995155 | 66 | |
| 93b6cd | 67 | - Optionally create a new Pyramid project using ``pcreate``: |
| 995155 | 68 | |
| 84b496 | 69 | $ cd $VENV |
| SP | 70 | $ bin/pcreate -s starter starter |
| 995155 | 71 | |
| 84b496 | 72 | - ...and install the new project into the virtual environment: |
| 995155 | 73 | |
| 84b496 | 74 | $ cd $VENV/starter |
| SP | 75 | $ $VENV/bin/pip install -e . |
| 995155 | 76 | |
| 84b496 | 77 | |
| SP | 78 | Using ``Tox`` |
| 79 | +++++++++++++ | |
| 995155 | 80 | |
| CM | 81 | Alternatively, if you already have ``tox`` installed, there is an easier |
| 82 | way to get going. | |
| 051e27 | 83 | |
| 93b6cd | 84 | - Create a new directory somewhere and ``cd`` to it: |
| 051e27 | 85 | |
| 84b496 | 86 | $ mkdir ~/hack-on-pyramid |
| SP | 87 | $ cd ~/hack-on-pyramid |
| 051e27 | 88 | |
| 93b6cd | 89 | - Check out a read-only copy of the Pyramid source: |
| 051e27 | 90 | |
| 84b496 | 91 | $ git clone git://github.com/Pylons/pyramid.git . |
| 051e27 | 92 | |
| e39cc8 | 93 | Alternatively, create a writeable fork on GitHub and clone it. |
| 051e27 | 94 | |
| 84b496 | 95 | Since Pyramid is a framework and not an application, it can be convenient to |
| SP | 96 | work against a sample application, preferably in its own virtual environment. A |
| 97 | quick way to achieve this is to use `tox | |
| 98 | <http://tox.readthedocs.org/en/latest/>`_ with a custom configuration file | |
| 99 | that is part of the checkout: | |
| 00a08a | 100 | |
| 84b496 | 101 | $ tox -c hacking-tox.ini |
| 00a08a | 102 | |
| 84b496 | 103 | This will create a python-2.7 based virtual environment named ``env27`` |
| SP | 104 | (Pyramid's ``.gitconfig` ignores all top-level folders that start with ``env`` |
| 105 | specifically in our use case), and inside that a simple pyramid application | |
| 106 | named ``hacking`` that you can then fire up like so: | |
| 00a08a | 107 | |
| 84b496 | 108 | $ cd env27/hacking |
| SP | 109 | $ ../bin/pip install -e ".[testing,docs]" |
| 110 | $ ../bin/pserve development.ini | |
| 111 | ||
| 051e27 | 112 | |
| 49f5c4 | 113 | Adding Features |
| CM | 114 | --------------- |
| 115 | ||
| 116 | In order to add a feature to Pyramid: | |
| 4f25f4 | 117 | |
| 84b496 | 118 | - The feature must be documented in both the API and narrative documentation |
| SP | 119 | (in ``docs/``). |
| 4f25f4 | 120 | |
| c8a5e0 | 121 | - The feature must work fully on the following CPython versions: 2.7, 3.4, 3.5, |
| SP | 122 | and 3.6 on both UNIX and Windows. |
| a3ff61 | 123 | |
| a5c810 | 124 | - The feature must work on the latest version of PyPy. |
| 4f25f4 | 125 | |
| 84b496 | 126 | - The feature must not depend on any particular persistence layer (filesystem, |
| SP | 127 | SQL, etc). |
| 4f25f4 | 128 | |
| 84b496 | 129 | - The feature must not add unnecessary dependencies (where "unnecessary" is of |
| SP | 130 | course subjective, but new dependencies should be discussed). |
| 4f25f4 | 131 | |
| 84b496 | 132 | The above requirements are relaxed for scaffolding dependencies. If a scaffold |
| SP | 133 | has an install-time dependency on something that doesn't work on a particular |
| 134 | platform, that caveat should be spelled out clearly in *its* documentation | |
| 135 | (within its ``docs/`` directory). | |
| 4f25f4 | 136 | |
| 49f5c4 | 137 | |
| CM | 138 | Coding Style |
| 139 | ------------ | |
| 140 | ||
| 84b496 | 141 | - PEP8 compliance. Whitespace rules are relaxed: not necessary to put two |
| SP | 142 | newlines between classes. But 79-column lines, in particular, are mandatory. |
| 1c561a | 143 | See https://docs.pylonsproject.org/en/latest/community/codestyle.html for more |
| 13b187 | 144 | information. |
| 49f5c4 | 145 | |
| cdcea9 | 146 | - Please do not remove trailing whitespace. Configure your editor to reduce |
| 8a3872 | 147 | diff noise. See https://github.com/Pylons/pyramid/issues/788 for more. |
| cdcea9 | 148 | |
| 84b496 | 149 | |
| a3ff61 | 150 | Running Tests |
| 8edd76 | 151 | ------------- |
| a3ff61 | 152 | |
| 84b496 | 153 | - To run all tests for Pyramid on a single Python version from your development |
| SP | 154 | virtual environment (See *Using a Development Checkout* above), run |
| 155 | ``nosetests``: | |
| 50f23d | 156 | |
| 84b496 | 157 | $ $VENV/bin/nosetests |
| SP | 158 | |
| 8edd76 | 159 | - To run individual tests (i.e., during development), you can use ``nosetests`` |
| SP | 160 | syntax as follows: |
| 161 | ||
| 162 | # run a single test | |
| 163 | $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName.test_mytestname | |
| 164 | ||
| 165 | # run all tests in a class | |
| 166 | $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName | |
| 167 | ||
| 168 | Optionally you can install a nose plugin, `nose-selecttests | |
| 62ab0f | 169 | <https://pypi.org/project/nose-selecttests/>`_, and use a regular |
| 8edd76 | 170 | expression with the ``-t`` parameter to run tests. |
| SP | 171 | |
| 172 | # run a single test | |
| 173 | $ $VENV/bin/nosetests -t test_mytestname | |
| a3ff61 | 174 | |
| 84b496 | 175 | - The ``tox.ini`` uses ``nose`` and ``coverage``. As such ``tox`` may be used |
| SP | 176 | to run groups of tests or only a specific version of Python. For example, the |
| 177 | following command will run tests on Python 2.7 only without coverage: | |
| 178 | ||
| 179 | $ tox -e py27 | |
| 180 | ||
| 181 | This command will run tests on the latest versions of Python 2 and 3 with | |
| 182 | coverage totaled for both versions. | |
| 183 | ||
| 184 | $ tox -e py2-cover,py3-cover,coverage | |
| 185 | ||
| 186 | - To run the full set of Pyramid tests on all platforms, install `tox | |
| 187 | <http://codespeak.net/~hpk/tox/>`_ into a system Python. The ``tox`` console | |
| 188 | script will be installed into the scripts location for that Python. While | |
| a3ff61 | 189 | ``cd``'ed to the Pyramid checkout root directory (it contains ``tox.ini``), |
| 84b496 | 190 | invoke the ``tox`` console script. This will read the ``tox.ini`` file and |
| SP | 191 | execute the tests on multiple Python versions and platforms. While it runs, |
| 192 | it creates a virtual environment for each version/platform combination. For | |
| 193 | example: | |
| a3ff61 | 194 | |
| 84b496 | 195 | $ sudo /usr/bin/pip install tox |
| SP | 196 | $ cd ~/hack-on-pyramid/ |
| 197 | $ /usr/bin/tox | |
| a3ff61 | 198 | |
| 84b496 | 199 | - The tests can also be run using `pytest <http://pytest.org/>`_. This is |
| SP | 200 | intended as a convenience for people who are more used to or fond of |
| 201 | ``pytest``. Run the tests like so: | |
| 7a2df2 | 202 | |
| 84b496 | 203 | $ $VENV/bin/pip install pytest |
| SP | 204 | $ $VENV/bin/py.test --strict pyramid/ |
| 205 | ||
| 206 | To run individual tests (i.e., during development), see "py.test usage - | |
| 207 | Specifying tests / selecting tests": | |
| 208 | http://pytest.org/latest/usage.html#specifying-tests-selecting-tests | |
| 7a2df2 | 209 | |
| 109b2a | 210 | - Functional tests related to the "scaffolds" (starter, zodb, alchemy) which |
| 84b496 | 211 | create a virtual environment, install the scaffold package and its |
| SP | 212 | dependencies, start a server, and hit a URL on the server, can be run like |
| 213 | so: | |
| 109b2a | 214 | |
| 84b496 | 215 | $ ./scaffoldtests.sh |
| aa1c9b | 216 | |
| 84b496 | 217 | Alternatively: |
| aa1c9b | 218 | |
| f362c7 | 219 | $ tox -e{py27,py34,py35,pypy}-scaffolds |
| 84b496 | 220 | |
| 109b2a | 221 | |
| 49f5c4 | 222 | Test Coverage |
| CM | 223 | ------------- |
| 224 | ||
| aa1c9b | 225 | - The codebase *must* have 100% test statement coverage after each commit. You |
| CM | 226 | can test coverage via ``./coverage.sh`` (which itself just executes ``tox |
| 227 | -epy2-cover,py3-cover,coverage``). | |
| 84b496 | 228 | |
| 49f5c4 | 229 | |
| c7fcdf | 230 | Documentation Coverage and Building HTML Documentation |
| CM | 231 | ------------------------------------------------------ |
| 49f5c4 | 232 | |
| c7fcdf | 233 | If you fix a bug, and the bug requires an API or behavior modification, all |
| 93b6cd | 234 | documentation in this package which references that API or behavior must be |
| SP | 235 | changed to reflect the bug fix, ideally in the same commit that fixes the bug |
| aa1c9b | 236 | or adds the feature. To build and review docs, use the following steps. |
| 49f5c4 | 237 | |
| 71d66b | 238 | 1. In the main Pyramid checkout directory, run ``./builddocs.sh`` (which just |
| 84b496 | 239 | turns around and runs ``tox -e docs``): |
| 995155 | 240 | |
| 84b496 | 241 | $ ./builddocs.sh |
| 995155 | 242 | |
| 71d66b | 243 | 2. Open the ``docs/_build/html/index.html`` file to see the resulting HTML |
| c7fcdf | 244 | rendering. |
| 84b496 | 245 | |
| 319806 | 246 | |
| 49f5c4 | 247 | Change Log |
| CM | 248 | ---------- |
| 249 | ||
| 250 | - Feature additions and bugfixes must be added to the ``CHANGES.txt`` | |
| 251 | file in the prevailing style. Changelog entries should be long and | |
| 252 | descriptive, not cryptic. Other developers should be able to know | |
| 253 | what your changelog entry means. | |
