Merge pull request #3356 from cdunklau/patch-2

Steve Piercy

2018-09-19 befe2ffe78ccb85f103973b000bb59d628f9c4fa

Merge pull request #3356 from cdunklau/patch-2

Tweak HACKING.txt - remove dead link, expunge reST markup

 HACKING.txt

@@ -8,9 +8,13 @@
----------------------------

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.
Pyramid checkout.  You can either do this by hand, or if you have `tox`
installed, you can use it to set up a working development environment.

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

Each installation method is described below.


By Hand
@@ -46,20 +50,20 @@
    $ cd ~/hack-on-pyramid
    $ python3 -m venv env

  From here on in within these instructions, the ``~/hack-on-pyramid/env``
  virtual environment you created above will be referred to as ``$VENV``.
  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.
  `export VENV=~/hack-on-pyramid/env` command.

- Install Pyramid from the checkout into the virtual environment, where the
  current working directory is the ``pyramid`` checkout directory. We will
  current working directory is the `pyramid` checkout directory. We will
  install Pyramid in editable (development) mode as well as its testing
  requirements.

    $ cd ~/hack-on-pyramid
    $ $VENV/bin/pip install -e ".[testing,docs]"

- Optionally create a new Pyramid project using ``pcreate``:
- Optionally create a new Pyramid project using `pcreate`:

    $ cd $VENV
    $ bin/pcreate -s starter starter
@@ -70,13 +74,13 @@
    $ $VENV/bin/pip install -e .


Using ``Tox``
+++++++++++++
Using `Tox`
+++++++++++

Alternatively, if you already have ``tox`` installed, there is an easier
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
@@ -89,16 +93,15 @@

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
quick way to achieve this is to use `tox` 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``
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:
named `hacking` that you can then fire up like so:

    $ cd env27/hacking
    $ ../bin/pip install -e ".[testing,docs]"
@@ -111,7 +114,7 @@
In order to add a feature to Pyramid:

- The feature must be documented in both the API and narrative documentation
  (in ``docs/``).
  (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.
@@ -127,7 +130,7 @@
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).
(within its `docs/` directory).


Coding Style
@@ -147,11 +150,11 @@

- To run all tests for Pyramid on a single Python version from your development
  virtual environment (See *Using a Development Checkout* above), run
  ``nosetests``:
  `nosetests`:

    $ $VENV/bin/nosetests

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

    # run a single test
@@ -160,14 +163,14 @@
    # 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.
  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
- 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:

@@ -178,22 +181,21 @@

    $ 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 virtual environment for each version/platform combination.  For
  example:
- To run the full set of Pyramid tests on all platforms, install `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 virtual environment
  for each version/platform combination.  For example:

    $ 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
- 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:
  `pytest`. Run the tests like so:

    $ $VENV/bin/pip install pytest
    $ $VENV/bin/py.test --strict pyramid/
@@ -218,8 +220,8 @@
-------------

- 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``).
  can test coverage via `./coverage.sh` (which itself just executes `tox
  -epy2-cover,py3-cover,coverage`).


Documentation Coverage and Building HTML Documentation
@@ -230,19 +232,19 @@
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 ``./builddocs.sh`` (which just
   turns around and runs ``tox -e docs``):
1. In the main Pyramid checkout directory, run `./builddocs.sh` (which just
   turns around and runs `tox -e docs`):

     $ ./builddocs.sh

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

- Feature additions and bugfixes must be added to the ``CHANGES.rst``
- 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.