view | history | commit | commitdiff
Michael Merickel
2018-10-18 e4c0570d5c67ddf0ad9502169b59475ba0784d82
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
8cc783 10 You will have to create a development environment to hack on Pyramid, using a
SP 11 Pyramid checkout.  We use `tox` to run tests, run test coverage, and build
12 documentation.
081699 13
8cc783 14 tox docs: https://tox.readthedocs.io/en/latest/
081699 15 tox on PyPI: https://pypi.org/project/tox/
051e27 16
081699 17 - Create a new directory somewhere and `cd` to it:
051e27 18
84b496 19     $ mkdir ~/hack-on-pyramid
SP 20     $ cd ~/hack-on-pyramid
051e27 21
93b6cd 22 - Check out a read-only copy of the Pyramid source:
051e27 23
84b496 24     $ git clone git://github.com/Pylons/pyramid.git .
051e27 25
e39cc8 26   Alternatively, create a writeable fork on GitHub and clone it.
84b496 27
051e27 28
49f5c4 29 Adding Features
CM 30 ---------------
31
32 In order to add a feature to Pyramid:
4f25f4 33
84b496 34 - The feature must be documented in both the API and narrative documentation
081699 35   (in `docs/`).
4f25f4 36
c8a5e0 37 - The feature must work fully on the following CPython versions: 2.7, 3.4, 3.5,
482075 38   3.6, and 3.7 on both UNIX and Windows.
a3ff61 39
a5c810 40 - The feature must work on the latest version of PyPy.
4f25f4 41
84b496 42 - The feature must not depend on any particular persistence layer (filesystem,
SP 43   SQL, etc).
4f25f4 44
84b496 45 - The feature must not add unnecessary dependencies (where "unnecessary" is of
SP 46   course subjective, but new dependencies should be discussed).
4f25f4 47
84b496 48 The above requirements are relaxed for scaffolding dependencies.  If a scaffold
SP 49 has an install-time dependency on something that doesn't work on a particular
50 platform, that caveat should be spelled out clearly in *its* documentation
081699 51 (within its `docs/` directory).
4f25f4 52
49f5c4 53
CM 54 Coding Style
55 ------------
56
8cc783 57 - Pyramid uses Black for code formatting style.
SP 58   https://pypi.org/project/black/
59   To run Black:
49f5c4 60
8cc783 61     $ tox -e black
cdcea9 62
84b496 63
a3ff61 64 Running Tests
8edd76 65 -------------
a3ff61 66
8cc783 67 - The `tox.ini` uses `nose` and `coverage`. As such `tox` may be used
SP 68   to run groups of tests or only a specific version of Python. For example, the
69   following command will run tests on Python 3.7 only without coverage:
50f23d 70
8cc783 71     $ tox -e py37
SP 72
73   This command will run tests on the latest versions of Python 2 and 3 with
74   coverage totaled for both versions.
75
76     $ tox -e py2-cover,py3-cover,coverage
84b496 77
081699 78 - To run individual tests (i.e., during development), you can use `nosetests`
8cc783 79   syntax as follows, where `$VENV` is an environment variable set to the path
SP 80   to your virtual environment:
8edd76 81
SP 82     # run a single test
83     $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName.test_mytestname
84
85     # run all tests in a class
86     $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName
87
8cc783 88   Optionally you can install a nose plugin `nose-selecttests` to run specific
SP 89   tests.
90   https://pypi.org/project/nose-selecttests/
91   For example, use a regular expression with the `-t` parameter to run tests.
8edd76 92
SP 93     # run a single test
94     $ $VENV/bin/nosetests -t test_mytestname
a3ff61 95
8cc783 96 - The tests can also be run using `pytest`.
SP 97   https://docs.pytest.org/en/latest/
98   This is intended as a convenience for people who prefer `pytest`. Run the
99   tests like so:
7a2df2 100
84b496 101     $ $VENV/bin/pip install pytest
8fcf0f 102     $ $VENV/bin/pytest --strict pyramid/
84b496 103
8fcf0f 104   To run individual tests (i.e., during development), see "pytest usage -
84b496 105   Specifying tests / selecting tests":
8cc783 106   https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests
7a2df2 107
109b2a 108 - Functional tests related to the "scaffolds" (starter, zodb, alchemy) which
84b496 109   create a virtual environment, install the scaffold package and its
SP 110   dependencies, start a server, and hit a URL on the server, can be run like
111   so:
109b2a 112
eadaee 113     $ tox -e{py27,py34,py35,py36,py37,pypy}-scaffolds
84b496 114
109b2a 115
49f5c4 116 Test Coverage
CM 117 -------------
118
aa1c9b 119 - The codebase *must* have 100% test statement coverage after each commit.  You
eadaee 120   can test coverage via `tox -epy2-cover,py3-cover,coverage`.
84b496 121
49f5c4 122
c7fcdf 123 Documentation Coverage and Building HTML Documentation
CM 124 ------------------------------------------------------
49f5c4 125
c7fcdf 126 If you fix a bug, and the bug requires an API or behavior modification, all
93b6cd 127 documentation in this package which references that API or behavior must be
SP 128 changed to reflect the bug fix, ideally in the same commit that fixes the bug
aa1c9b 129 or adds the feature.  To build and review docs, use the following steps.
49f5c4 130
eadaee 131 1. In the main Pyramid checkout directory, run `tox -e docs`:
995155 132
eadaee 133      $ tox -e docs
995155 134
081699 135 2. Open the `docs/_build/html/index.html` file to see the resulting HTML
c7fcdf 136    rendering.
84b496 137
319806 138
49f5c4 139 Change Log
CM 140 ----------
141
081699 142 - Feature additions and bugfixes must be added to the `CHANGES.rst`
49f5c4 143   file in the prevailing style.  Changelog entries should be long and
CM 144   descriptive, not cryptic.  Other developers should be able to know
145   what your changelog entry means.