/
HACKING.txt
114 lines (76 loc) · 3.48 KB
/
HACKING.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
Hacking on Pyramid
==================
Here are some guidelines about hacking on Pyramid.
Using a Development Checkout
----------------------------
Below is a quick start on creating a development environment using a Pyramid
checkout.
- Create a new directory somewhere and ``cd`` to it::
$ mkdir ~/hack-on-pyramid
$ cd ~/hack-on-pyramid
- Check out a read-only copy of the Pyramid source::
$ git clone git://github.com/Pylons/pyramid.git
(alternately, create a writeable fork on GitHub and check that out).
- Create a virtualenv in which to install Pyramid::
$ virtualenv2.6 --no-site-packages env
- Install ``setuptools-git`` into the virtualenv (for good measure, as we're
using git to do version control)::
$ env/bin/easy_install setuptools-git
- Install ``nose`` and ``coverage`` into the virtualenv (for running nose
tests with coverage via ``setup.py nosetests --with-coverage``)::
$ env/bin/easy_install nose coverage
- Install Pyramid from the checkout into the virtualenv using ``setup.py
develop`` (running ``setup.py develop`` *must* be done while the current
working directory is the ``pyramid`` checkout directory)::
$ cd pyramid
$ ../env/bin/python setup.py develop
- At that point, you should be able to create new Pyramid projects by using
``paster create``::
$ cd ../env
$ bin/paster create -t pyramid_starter starter
- And install those projects (also using ``setup.py develop``) into the
virtualenv::
$ cd starter
$ ../bin/python setup.py develop
Adding Features
---------------
In order to add a feature to Pyramid:
- The feature must be documented in both the API and narrative
documentation (in ``docs/``).
- The feature must work fully on the following CPython versions: 2.4,
2.5, 2.6, and 2.7 on both UNIX and Windows.
- The feature must not cause installation or runtime failure on Jython
or App Engine. If it doesn't cause installation or runtime failure,
but doesn't actually *work* on these platforms, that caveat should be
spelled out in the documentation.
- The feature must not depend on any particular persistence layer
(filesystem, SQL, etc).
- The feature must not add unnecessary dependencies (where
"unnecessary" is of course subjective, but new dependencies should
be discussed).
The above requirements are relaxed for paster template dependencies.
If a paster template has an install-time dependency on something that
doesn't work on a particular platform, that caveat should be spelled
out clearly in *its* documentation (within its ``docs/`` directory).
Coding Style
------------
- PEP8 compliance. Whitespace rules are relaxed: not necessary to put
2 newlines between classes. But 80-column lines, in particular, are
mandatory.
Test Coverage
-------------
- The codebase *must* have 100% test statement coverage after each
commit. You can test coverage via ``python setup.py nosetests
--with-coverage`` (requires the ``nose`` and ``coverage`` packages).
Documentation Coverage
----------------------
- If you fix a bug, and the bug requires an API or behavior
modification, all documentation in this package which references
that API or behavior must change to reflect the bug fix, ideally in
the same commit that fixes the bug or adds the feature.
Change Log
----------
- Feature additions and bugfixes must be added to the ``CHANGES.txt``
file in the prevailing style. Changelog entries should be long and
descriptive, not cryptic. Other developers should be able to know
what your changelog entry means.