diff options
Diffstat (limited to 'HACKING.txt')
| -rw-r--r-- | HACKING.txt | 105 |
1 files changed, 65 insertions, 40 deletions
diff --git a/HACKING.txt b/HACKING.txt index b32a8a957..460d02047 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -1,45 +1,64 @@ Hacking on Pyramid ================== -Here are some guidelines about hacking on Pyramid. +Here are some guidelines for hacking on Pyramid. Using a Development Checkout ---------------------------- -You'll have to create a development environment to hack on Pyramid, using a -Pyramid checkout. You can either do this by hand or, if you have ``tox`` -installed (it's on PyPI), you can (ab)use tox to get a working development +You'll have to create a development environment to hack on Pyramid, using a +Pyramid checkout. You can either do this by hand, or if you have ``tox`` +installed (it's on PyPI), you can use tox to set up a working development environment. Each installation method is described below. By Hand +++++++ -- Check out Pyramid from source:: +- While logged into your GitHub account, navigate to the Pyramid repo on + GitHub. + + https://github.com/Pylons/pyramid + +- Fork and clone the Pyramid repository to your GitHub account by clicking + the "Fork" button. + +- Clone your fork of Pyramid from your GitHub account to your local computer, + substituting your account username and specifying the destination as + "hack-on-pyramid". $ cd ~ - $ git clone git://github.com/Pylons/pyramid.git hack-on-pyramid + $ git clone git@github.com:USERNAME/pyramid.git hack-on-pyramid $ cd hack-on-pyramid + # Configure remotes such that you can pull changes from the Pyramid + # repository into your local repository. + $ git remote add upstream git@github.com:Pylons/pyramid.git + # fetch and merge changes from upstream into master + $ git fetch upstream + $ git merge upstream/master + +Now your local repo is set up such that you will push changes to your GitHub +repo, from which you can submit a pull request. -- Create a virtualenv in which to install Pyramid:: +- Create a virtualenv in which to install Pyramid: $ cd ~/hack-on-pyramid $ virtualenv -ppython2.7 env - Note that very old versions of virtualenv (virtualenv versions below, say, + Note that very old versions of virtualenv (virtualenv versions below, say, 1.10 or thereabouts) require you to pass a ``--no-site-packages`` flag to get a completely isolated environment. - You can choose which Python version you want to use by passing a ``-p`` + You can choose which Python version you want to use by passing a ``-p`` flag to ``virtualenv``. For example, ``virtualenv -ppython2.7`` chooses the Python 2.7 interpreter to be installed. - From here on in within these instructions, the ``~/hack-on-pyramid/env`` + From here on in within these instructions, the ``~/hack-on-pyramid/env`` virtual environment you created above will be referred to as ``$VENV``. To use the instructions in the steps that follow literally, use the ``export VENV=~/hack-on-pyramid/env`` command. - Install ``setuptools-git`` into the virtualenv (for good measure, as we're - using git to do version control):: + using git to do version control): $ $VENV/bin/easy_install setuptools-git @@ -47,19 +66,18 @@ By Hand 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 - ``pyramid`` checkout directory:: + ``pyramid`` checkout directory: $ cd ~/hack-on-pyramid $ $VENV/bin/python setup.py dev -- At that point, you should be able to create new Pyramid projects by using - ``pcreate``:: +- Optionally create a new Pyramid project using ``pcreate``: $ cd $VENV $ bin/pcreate -s starter starter -- And install those projects (also using ``setup.py develop``) into the - virtualenv:: +- ...and install the new project (also using ``setup.py develop``) into the + virtualenv: $ cd $VENV/starter $ $VENV/bin/python setup.py develop @@ -70,12 +88,12 @@ Using Tox Alternatively, if you already have ``tox`` installed, there is an easier way to get going. -- Create a new directory somewhere and ``cd`` to it:: +- 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:: +- Check out a read-only copy of the Pyramid source: $ git clone git://github.com/Pylons/pyramid.git . @@ -85,14 +103,14 @@ Since Pyramid is a framework and not an application, it can be convenient to work against a sample application, preferably in its own virtualenv. A quick way to achieve this is to (ab-)use ``tox`` (http://tox.readthedocs.org/en/latest/) with a custom configuration -file that's part of the checkout:: +file that's part of the checkout: tox -c hacking-tox.ini This will create a python-2.7 based virtualenv named ``env27`` (Pyramid's ``.gitconfig` ignores all top-level folders that start with ``env`` specifically for this use case) and inside that a simple pyramid application named -``hacking`` that you can then fire up like so:: +``hacking`` that you can then fire up like so: cd env27/hacking ../bin/pserve development.ini @@ -132,7 +150,7 @@ 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 + mandatory. See http://docs.pylonsproject.org/en/latest/community/codestyle.html for more information. @@ -142,14 +160,14 @@ Coding Style Running Tests -------------- -- To run all tests for Pyramid on a single Python version, run ``nosetests`` +- To run all tests for Pyramid on a single Python version, run ``nosetests`` from your development virtualenv (See *Using a Development Checkout* above). - 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 + <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. - To run the full set of Pyramid tests on all platforms, install ``tox`` @@ -159,7 +177,7 @@ Running Tests invoke the ``tox`` console script. This will read the ``tox.ini`` file and execute the tests on multiple Python versions and platforms; while it runs, it creates a virtualenv for each version/platform combination. For - example:: + example: $ sudo /usr/bin/easy_install tox $ cd ~/hack-on-pyramid/ @@ -167,7 +185,7 @@ Running Tests - The tests can also be run using ``pytest`` (http://pytest.org/). This is intended as a convenience for people who are more used or fond of ``pytest``. - Run the tests like so:: + Run the tests like so: $ $VENV/bin/easy_install pytest $ py.test --strict pyramid/ @@ -184,39 +202,47 @@ 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 +documentation in this package which references that API or behavior must be +changed to reflect the bug fix, ideally in the same commit that fixes the bug or adds the feature. To build and review docs (where ``$VENV`` refers to the virtualenv you're using to develop Pyramid): -1. After following the steps above in "Using a Development Checkout", cause - Sphinx and all development requirements to be installed in your - virtualenv:: +1. After following the steps above in "Using a Development Checkout", install + Sphinx and all development requirements in your virtualenv: $ cd ~/hack-on-pyramid $ $VENV/bin/python setup.py docs 2. Update all git submodules from the top-level of your Pyramid checkout, like - so:: + so: $ git submodule update --init --recursive This will checkout theme subrepositories and prevent error conditions when HTML docs are generated. -3. cd to the ``docs`` directory within your Pyramid checkout and execute - the ``make`` command with some flags:: +3. Next change into the submodule's directory and switch to a branch so that + the submodule repositories are no longer "headless". Then update the + repository to ensure that we have the latest updates. + See http://chrisjean.com/2009/04/20/git-submodules-adding-using-removing-and-updating/ + + $ cd docs/_themes + $ git checkout master + $ git pull + +4. Change into the ``docs`` directory within your Pyramid checkout and execute + the ``make`` command with some flags: $ cd ~/hack-on-pyramid/pyramid/docs $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build - The ``SPHINXBUILD=...`` hair is there in order to tell it to use the - virtualenv Python, which will have both Sphinx and Pyramid (for API - documentation generation) installed. + The ``SPHINXBUILD=...`` argument tells Sphinx to use the virtualenv Python, + which will have both Sphinx and Pyramid (for API documentation generation) + installed. -4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML +5. Open the ``docs/_build/html/index.html`` file to see the resulting HTML rendering. Change Log @@ -227,4 +253,3 @@ Change Log descriptive, not cryptic. Other developers should be able to know what your changelog entry means. - |