Remove by hand method. We use tox. Remove reference to hacking-tox.ini and ...

Steve Piercy

2018-10-15 8cc7834c93f71ac87a493a3018c32a75c3cca390

Remove by hand method. We use tox.
Remove reference to hacking-tox.ini and let developer decide how to start a project.
Update Coding Style for Black, removing previous style.
Move nose testing instructions after tox, but before pytest.
Update links.

 HACKING.txt

@@ -7,78 +7,12 @@
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, you can use it to set up a working development 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.

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

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 virtual environment in which to install Pyramid:

    $ 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`.
  To use the instructions in the steps that follow literally, use the
  `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
  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`:

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

@@ -90,22 +24,6 @@
    $ 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` 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
@@ -136,26 +54,30 @@
Coding Style
------------

- PEP8 compliance.  Whitespace rules are relaxed: not necessary to put two
  newlines between classes.  But 79-column lines, in particular, are mandatory.
  See https://pylonsproject.org/community-coding-style-standards.html for more
  information.
- Pyramid uses Black for code formatting style.
  https://pypi.org/project/black/
  To run Black:

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


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

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

    $ $VENV/bin/nosetests
    $ 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:
  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
@@ -163,46 +85,25 @@
    # 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` 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 `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` 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
  intended as a convenience for people who are more used to or fond of
  `pytest`. Run the tests like so:
- 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":
  http://pytest.org/latest/usage.html#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