diff options
Diffstat (limited to 'HACKING.txt')
| -rw-r--r-- | HACKING.txt | 262 |
1 files changed, 70 insertions, 192 deletions
diff --git a/HACKING.txt b/HACKING.txt index 1386be3af..acd65e4fd 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -3,200 +3,110 @@ 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 use tox to set up a working development -environment. Each installation method is described below. - -By Hand -+++++++ - -- 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: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 https://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: - - $ cd ~/hack-on-pyramid - $ virtualenv -ppython2.7 env - - 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 will have to create a development environment to hack on Pyramid, using a +Pyramid checkout. We use `tox` to run tests, run test coverage, and build +documentation. - 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. +tox docs: https://tox.readthedocs.io/en/latest/ +tox on PyPI: https://pypi.org/project/tox/ - 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. +- Create a new directory somewhere and `cd` to it: -- Install ``setuptools-git`` into the virtualenv (for good measure, as we're - using git to do version control): + $ mkdir ~/hack-on-pyramid + $ cd ~/hack-on-pyramid - $ $VENV/bin/easy_install setuptools-git - -- Install Pyramid 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 - ``pyramid`` checkout directory: +- Check out a read-only copy of the Pyramid source: - $ cd ~/hack-on-pyramid - $ $VENV/bin/python setup.py dev + $ git clone git://github.com/Pylons/pyramid.git . -- Optionally create a new Pyramid project using ``pcreate``: + Alternatively, create a writeable fork on GitHub and clone it. - $ cd $VENV - $ bin/pcreate -s starter starter -- ...and install the new project (also using ``setup.py develop``) into the - virtualenv: +Adding Features +--------------- - $ cd $VENV/starter - $ $VENV/bin/python setup.py develop +In order to add a feature to Pyramid: -Using Tox -+++++++++ +- The feature must be documented in both the API and narrative documentation + (in `docs/`). -Alternatively, if you already have ``tox`` installed, there is an easier -way to get going. +- The feature must work fully on the following CPython versions: 2.7, 3.4, 3.5, + 3.6, and 3.7 on both UNIX and Windows. -- Create a new directory somewhere and ``cd`` to it: +- The feature must work on the latest version of PyPy. - $ mkdir ~/hack-on-pyramid - $ cd ~/hack-on-pyramid +- The feature must not depend on any particular persistence layer (filesystem, + SQL, etc). -- Check out a read-only copy of the Pyramid source: +- The feature must not add unnecessary dependencies (where "unnecessary" is of + course subjective, but new dependencies should be discussed). - $ git clone git://github.com/Pylons/pyramid.git . - (alternately, create a writeable fork on GitHub and check that out). +Coding Style +------------ -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: +- Pyramid uses Black for code formatting style. + https://pypi.org/project/black/ + To run Black: - tox -c hacking-tox.ini + $ tox -e black -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: - cd env27/hacking - ../bin/pserve development.ini +Running Tests +------------- -Adding Features ---------------- +- The `tox.ini` uses `nose` and `coverage`. As such `tox` may be used + to run groups of tests or only a specific version of Python. For example, the + following command will run tests on Python 3.7 only without coverage: -In order to add a feature to Pyramid: + $ tox -e py37 -- The feature must be documented in both the API and narrative - documentation (in ``docs/``). + This command will run tests on the latest versions of Python 2 and 3 with + coverage totaled for both versions. -- The feature must work fully on the following CPython versions: 2.6, - 2.7, 3.2, and 3.3 on both UNIX and Windows. + $ tox -e py2-cover,py3-cover,coverage -- The feature must work on the latest version of PyPy. +- To run individual tests (i.e., during development), you can use `nosetests` + syntax as follows, where `$VENV` is an environment variable set to the path + to your virtual environment: -- The feature must not cause installation or runtime failure on 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. + # run a single test + $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName.test_mytestname -- The feature must not depend on any particular persistence layer - (filesystem, SQL, etc). + # run all tests in a class + $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course subjective, but new dependencies should - be discussed). + Optionally you can install a nose plugin `nose-selecttests` to run specific + tests. + https://pypi.org/project/nose-selecttests/ + For example, use a regular expression with the `-t` parameter to run tests. -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). + # run a single test + $ $VENV/bin/nosetests -t test_mytestname -Coding Style ------------- +- The tests can also be run using `pytest`. + https://docs.pytest.org/en/latest/ + This is intended as a convenience for people who prefer `pytest`. Run the + tests like so: -- PEP8 compliance. Whitespace rules are relaxed: not necessary to put - 2 newlines between classes. But 79-column lines, in particular, are - mandatory. See - http://docs.pylonsproject.org/en/latest/community/codestyle.html for more - information. + $ $VENV/bin/pip install pytest + $ $VENV/bin/pytest --strict pyramid/ -- Please do not remove trailing whitespace. Configure your editor to reduce - diff noise. See https://github.com/Pylons/pyramid/issues/788 for more. + To run individual tests (i.e., during development), see "pytest usage - + Specifying tests / selecting tests": + https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests -Running Tests --------------- - -- 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 - working on. - -- To run the full set of Pyramid tests on all platforms, install ``tox`` - (http://codespeak.net/~hpk/tox/) into a system Python. The ``tox`` console - script will be installed into the scripts location for that Python. While - ``cd``'ed to the Pyramid checkout root directory (it contains ``tox.ini``), - 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: - - $ sudo /usr/bin/easy_install tox - $ cd ~/hack-on-pyramid/ - $ /usr/bin/tox - -- 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: - - $ $VENV/bin/easy_install pytest - $ py.test --strict pyramid/ 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``. +- The codebase *must* have 100% test statement coverage after each commit. You + can test coverage via `tox -epy2-cover,py3-cover,coverage`. + Documentation Coverage and Building HTML Documentation ------------------------------------------------------ @@ -204,52 +114,20 @@ 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 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): +or adds the feature. To build and review docs, use the following steps. -1. After following the steps above in "Using a Development Checkout", install - Sphinx and all development requirements in your virtualenv: +1. In the main Pyramid checkout directory, run `tox -e docs`: - $ cd ~/hack-on-pyramid - $ $VENV/bin/python setup.py docs + $ tox -e docs -2. Update all git submodules from the top-level of your Pyramid checkout, like - so: - - $ git submodule update --init --recursive - - This will checkout theme subrepositories and prevent error conditions when - HTML docs are generated. - -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=...`` argument tells Sphinx to use the virtualenv Python, - which will have both Sphinx and Pyramid (for API documentation generation) - installed. - -5. Open the ``docs/_build/html/index.html`` file to see the resulting HTML +2. Open the `.tox/docs/html/index.html` file to see the resulting HTML rendering. + Change Log ---------- -- Feature additions and bugfixes must be added to the ``CHANGES.txt`` +- Feature additions and bugfixes must be added to the `CHANGES.rst` 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. - |