Merge pull request #3365 from stevepiercy/1.8-branch

Steve Piercy

2018-09-22 e22970cd21eb36c2a658c843bb5cb4f59d77fd19

 HACKING.txt

@@ -1,151 +1,248 @@
Hacking on Pyramid
==================

Here are some guidelines about hacking on Pyramid.
Here are some guidelines for hacking on Pyramid.


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

Below is a quick start on creating a development environment using a Pyramid
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.

- Create a new directory somewhere and ``cd`` to it::

  $ mkdir ~/hack-on-pyramid
  $ cd ~/hack-on-pyramid
By Hand
+++++++

- Check out a read-only copy of the Pyramid source::
- While logged into your GitHub account, navigate to the Pyramid repo on
  GitHub.
  
  https://github.com/Pylons/pyramid

  $ git clone git://github.com/Pylons/pyramid.git
- Fork and clone the Pyramid repository to your GitHub account by clicking
  the "Fork" button.

  (alternately, create a writeable fork on GitHub and check that out).
- 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".

- Create a virtualenv in which to install 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

  $ virtualenv2.6 --no-site-packages env
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.

- Install ``setuptools-git`` into the virtualenv (for good measure, as we're
  using git to do version control)::
- Create a virtual environment in which to install Pyramid:

  $ $VENV/bin/easy_install setuptools-git
    $ cd ~/hack-on-pyramid
    $ python3 -m venv env

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

  $ cd pyramid
  $ $VENV/bin/python setup.py dev
- Install ``setuptools-git`` into the virtual environment (for good measure, as
  we're using git to do version control):

- At that point, you should be able to create new Pyramid projects by using
  ``pcreate``::
    $ $VENV/bin/pip install setuptools-git

  $ cd ../env
  $ $VENV/bin/pcreate -s starter starter
- Install Pyramid from the checkout into the virtual environment, where the
  current working directory is the ``pyramid`` checkout directory. We will
  install Pyramid in editable (development) mode as well as its testing
  requirements.

- And install those projects (also using ``setup.py develop``) into the
  virtualenv::
    $ cd ~/hack-on-pyramid
    $ $VENV/bin/pip install -e ".[testing,docs]"

  $ cd starter
  $ $VENV/bin/python setup.py develop
- Optionally create a new Pyramid project using ``pcreate``:

    $ cd $VENV
    $ bin/pcreate -s starter starter

- ...and install the new project into the virtual environment:

    $ cd $VENV/starter
    $ $VENV/bin/pip install -e .


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:

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

Since Pyramid is a framework and not an application, it can be convenient to
work against a sample application, preferably in its own virtual environment. A
quick way to achieve this is to use `tox
<http://tox.readthedocs.org/en/latest/>`_ with a custom configuration file
that is part of the checkout:

    $ tox -c hacking-tox.ini

This will create a python-2.7 based virtual environment named ``env27``
(Pyramid's ``.gitconfig` ignores all top-level folders that start with ``env``
specifically in our use case), and inside that a simple pyramid application
named ``hacking`` that you can then fire up like so:

    $ cd env27/hacking
    $ ../bin/pip install -e ".[testing,docs]"
    $ ../bin/pserve development.ini


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 be documented in both the API and narrative documentation
  (in ``docs/``).

- The feature must work fully on the following CPython versions: 2.6,
  2.7, and 3.2 on both UNIX and Windows.
- The feature must work fully on the following CPython versions: 2.7, 3.4, 3.5,
  and 3.6 on both UNIX and Windows.

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

- 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.
- The feature must not depend on any particular persistence layer (filesystem,
  SQL, etc).

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

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

- PEP8 compliance.  Whitespace rules are relaxed: not necessary to put
  2 newlines between classes.  But 80-column lines, in particular, are
  mandatory.
- PEP8 compliance.  Whitespace rules are relaxed: not necessary to put two
  newlines between classes.  But 79-column lines, in particular, are mandatory.
  See https://docs.pylonsproject.org/en/latest/community/codestyle.html for more
  information.

- Please do not remove trailing whitespace.  Configure your editor to reduce
  diff noise. See https://github.com/Pylons/pyramid/issues/788 for more.


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

- To run tests for Pyramid on a single Python version, run ``python setup.py
  test`` against the Python interpreter from virtualenv into which
  you've ``setup.py develop``-ed Pyramid.
- To run all tests for Pyramid on a single Python version from your development
  virtual environment (See *Using a Development Checkout* above), run
  ``nosetests``:

- 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
    $ $VENV/bin/nosetests

- To run individual tests (i.e., during development), you can use ``nosetests``
  syntax as follows:

    # 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
  <https://pypi.org/project/nose-selecttests/>`_, and use a regular
  expression with the ``-t`` parameter to run tests.

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

- 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 2.7 only without coverage:

    $ tox -e py27

  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 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::
  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 virtual environment for each version/platform combination.  For
  example:

   $ /usr/bin/easy_install tox
   $ cd ~/hack-on-pyramid/pyramid
   $ /usr/bin/tox
    $ sudo /usr/bin/pip 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 to or fond of
  ``pytest``. Run the tests like so:

    $ $VENV/bin/pip install pytest
    $ $VENV/bin/py.test --strict pyramid/

  To run individual tests (i.e., during development), see "py.test usage -
  Specifying tests / selecting tests":
  http://pytest.org/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:

    $ ./scaffoldtests.sh

  Alternatively:

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


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 ``./coverage.sh`` (which itself just executes ``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
change to reflect the bug fix, ideally in the same commit that fixes the bug
or adds the feature.
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.

To build and review docs (where ``$yourvenv`` refers to the virtualenv you're
using to develop Pyramid):
1. In the main Pyramid checkout directory, run ``./builddocs.sh`` (which just
   turns around and runs ``tox -e docs``):

1. Run ``$VENV/bin/python setup.py dev docs``.  This will cause Sphinx
   and all development requirements to be installed in your virtualenv.
     $ ./builddocs.sh

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. cd to the ``docs`` directory within your Pyramid checkout and execute
   ``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.

4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML
2. Open the ``docs/_build/html/index.html`` file to see the resulting HTML
   rendering.


Change Log
----------
@@ -154,5 +251,3 @@
  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.