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