/
HACKING.txt
155 lines (105 loc) · 5.2 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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
Hacking on Substance D
======================
Here are some guidelines about hacking on Substance D.
Using a Development Checkout
----------------------------
Below is a quick start on creating a development environment using a
Substance D checkout.
- Create a new directory somewhere and ``cd`` to it::
$ mkdir ~/hack-on-substanced
$ cd ~/hack-on-substanced
- Check out a read-only copy of the Substance D source::
$ git clone git://github.com/Pylons/substanced.git
(alternately, create a writeable fork on GitHub and check that out).
- Create a virtualenv in which to install Substance D::
$ virtualenv -p python2.7 --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 Substance D from the checkout into the virtualenv using ``setup.py
dev``. ``setup.py dev`` is an alias for "setup.py develop" which also
installs testing requirements such as nose and coverage. Running
``setup.py dev`` *must* be done while the current working directory is the
``substanced`` checkout directory::
$ cd substanced
$ ../env/bin/python setup.py dev
- At that point, you should be able to create new Substance D projects by using
``pcreate``::
$ cd ../env
$ bin/pcreate -s substanced myproj
- And install that project using ``setup.py develop`` into the
virtualenv::
$ cd myproj
$ ../bin/python setup.py develop
- Run the resulting project via ``../bin/pserve development.ini``.
Adding Features
---------------
In order to add a feature to Substance D:
- 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.6, 2.7,
3.2, and 3.3 on both UNIX and Windows.
- The feature must work on the latest version of PyPy.
- 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 scaffolding dependencies. If a
scaffold 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. See
http://docs.pylonsproject.org/en/latest/community/codestyle.html for more
information.
- Please do not remove trailing whitespace. Configure your editor to reduce
diff noise. See https://github.com/Pylons/pyramid/issues/788 for more.
Running Substance D Tests
-------------------------
To run the full test suite (your system will need Python 2.6, 2.7, 3.2, and 3.3
to be installed):
- Install "tox" (``easy_install tox``).
- Run ``tox`` from within the top-level ``substanced`` directory.
To run all tests for a single version of Python:
- Run ``setup.py dev`` (this will install ``coverage`` and ``nose``).
- Run ``setup.py nosetests``.
To run coverage tests for a single version of Python:
- Run ``setup.py dev`` (this will install ``coverage`` and ``nose``).
- Run ``setup.py nosetests --with-coverage``.
- To run individual tests (i.e. during development) you can use a regular
expression with the ``-t`` parameter courtesy of the `nose-selecttests
<https://pypi.python.org/pypi/nose-selecttests/>`_ plugin that's been
installed (along with nose itself) via ``python setup.py dev``. The
easiest usage is to simply provide the verbatim name of the test you're
working on.
Test Coverage
-------------
- The codebase *must* have 100% test statement coverage after each commit.
You can test coverage via ``tox -e coverage``, or alternately by installing
``nose`` and ``coverage`` into your virtualenv (easiest via ``setup.py
dev``), and running ``setup.py nosetests --with-coverage``.
Documentation Coverage and Building HTML Documentation
------------------------------------------------------
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.
To build and review docs (where ``$yourvenv`` refers to the virtualenv you're
using to develop substanced):
1. Run ``$yourvenv/bin/python setup.py dev docs``. This will cause Sphinx
and all development requirements to be installed in your virtualenv.
2. cd to the ``docs`` directory within your substanced checkout and execute
``make clean html SPHINXBUILD=$yourvenv/bin/sphinx-build``. The
``SPHINXBUILD=...`` hair is there in order to tell it to use the
virtualenv Python, which will have both Sphinx and SubstanceD (for API
documentation generation) installed.
3. Open the ``docs/_build/html/index.html`` file to see the resulting HTML
rendering.
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.