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. |
|
143 |
See http://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 |
|
169 |
<https://pypi.python.org/pypi/nose-selecttests/>`_, and use a regular |
|
170 |
expression with the ``-t`` parameter to run tests. |
|
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. |