Hacking on Pyramid
==================

Here are some guidelines for hacking on Pyramid.


Using a Development Checkout
----------------------------

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.

tox docs: https://tox.readthedocs.io/en/latest/
tox on PyPI: https://pypi.org/project/tox/

- 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:

    $ git clone git://github.com/Pylons/pyramid.git .

  Alternatively, create a writeable fork on GitHub and clone it.


Adding Features
---------------

In order to add a feature to Pyramid:

- 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.7, 3.4, 3.5,
  3.6, and 3.7 on both UNIX and Windows.

- The feature must work on the latest version of PyPy.

- The feature must not depend on any particular persistence layer (filesystem,
  SQL, etc).

- 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
------------

- Pyramid uses Black for code formatting style.
  https://pypi.org/project/black/
  To run Black:

    $ tox -e black


Running Tests
-------------

- 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:

    $ tox -e py37

  This command will run tests on the latest versions of Python 2 and 3 with
  coverage totaled for both versions.

    $ tox -e py2-cover,py3-cover,coverage

- 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:

    # run a single test
    $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName.test_mytestname

    # run all tests in a class
    $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName

  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.

    # run a single test
    $ $VENV/bin/nosetests -t test_mytestname

- 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:

    $ $VENV/bin/pip install pytest
    $ $VENV/bin/pytest --strict pyramid/

  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

- Functional tests related to the "scaffolds" (starter, zodb, alchemy) which
  create a virtual environment, install the scaffold package and its
  dependencies, start a server, and hit a URL on the server, can be run like
  so:

    $ tox -e{py27,py34,py35,py36,py37,pypy}-scaffolds


Test 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
------------------------------------------------------

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, use the following steps.

1. In the main Pyramid checkout directory, run `tox -e docs`:

     $ tox -e docs

2. 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.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.