| 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 | ||
| 32 | - Install Pyramid from the checkout into the virtualenv using ``setup.py | |
| 33 | develop`` (running ``setup.py develop`` *must* be done while the current | |
| 34 | working directory is the ``pyramid`` checkout directory):: | |
| 35 | ||
| 36 | $ cd pyramid | |
| 37 | $ ../env/bin/python setup.py develop | |
| 38 | ||
| 39 | - At that point, you should be able to create new Pyramid projects by using | |
| 40 | ``paster create``:: | |
| 41 | ||
| 42 | $ cd ../env | |
| 43 | $ bin/paster create -t pyramid_starter starter | |
| 44 | ||
| 45 | - And install those projects (also using ``setup.py develop``) into the | |
| 46 | virtualenv:: | |
| 47 | ||
| 48 | $ cd starter | |
| 49 | $ ../bin/python setup.py develop | |
| 50 | ||
| 49f5c4 | 51 | Adding Features |
| CM | 52 | --------------- |
| 53 | ||
| 54 | In order to add a feature to Pyramid: | |
| 4f25f4 | 55 | |
| CM | 56 | - The feature must be documented in both the API and narrative |
| 49f5c4 | 57 | documentation (in ``docs/``). |
| 4f25f4 | 58 | |
| CM | 59 | - The feature must work fully on the following CPython versions: 2.4, |
| 60 | 2.5, 2.6, and 2.7 on both UNIX and Windows. | |
| 61 | ||
| 62 | - The feature must not cause installation or runtime failure on Jython | |
| 63 | or App Engine. If it doesn't cause installation or runtime failure, | |
| 64 | but doesn't actually *work* on these platforms, that caveat should be | |
| 65 | spelled out in the documentation. | |
| 66 | ||
| 67 | - The feature must not depend on any particular persistence layer | |
| 68 | (filesystem, SQL, etc). | |
| 69 | ||
| 70 | - The feature must not add unnecessary dependencies (where | |
| 71 | "unnecessary" is of course subjective, but new dependencies should | |
| 72 | be discussed). | |
| 73 | ||
| 74 | The above requirements are relaxed for paster template dependencies. | |
| 49f5c4 | 75 | If a paster template has an install-time dependency on something that |
| CM | 76 | doesn't work on a particular platform, that caveat should be spelled |
| 77 | out clearly in *its* documentation (within its ``docs/`` directory). | |
| 78 | ||
| 79 | Coding Style | |
| 80 | ------------ | |
| 81 | ||
| 82 | - PEP8 compliance. Whitespace rules are relaxed: not necessary to put | |
| 83 | 2 newlines between classes. But 80-column lines, in particular, are | |
| 84 | mandatory. | |
| 85 | ||
| 86 | Test Coverage | |
| 87 | ------------- | |
| 88 | ||
| 89 | - The codebase *must* have 100% test statement coverage after each | |
| 90 | commit. You can test coverage via ``python setup.py nosetests | |
| 91 | --with-coverage`` (requires the ``nose`` and ``coverage`` packages). | |
| 92 | ||
| 93 | Documentation Coverage | |
| 94 | ---------------------- | |
| 95 | ||
| 96 | - If you fix a bug, and the bug requires an API or behavior | |
| 97 | modification, all documentation in this package which references | |
| 98 | that API or behavior must change to reflect the bug fix, ideally in | |
| 99 | the same commit that fixes the bug or adds the feature. | |
| 100 | ||
| 101 | Change Log | |
| 102 | ---------- | |
| 103 | ||
| 104 | - Feature additions and bugfixes must be added to the ``CHANGES.txt`` | |
| 105 | file in the prevailing style. Changelog entries should be long and | |
| 106 | descriptive, not cryptic. Other developers should be able to know | |
| 107 | what your changelog entry means. | |
| 108 | ||
| 109 | ||
