diff options
author | Steve Piercy <web@stevepiercy.com> | 2018-05-19 16:25:02 -0700 |
---|---|---|
committer | Steve Piercy <web@stevepiercy.com> | 2018-05-19 16:25:02 -0700 |
commit | 33f68da9e2d45c228ce396fd4e9d1c3e24577f66 (patch) | |
tree | a5865612ab67d5b3b2918d363cc6526a49222465 | |
parent | 02c9dc5b0384ba8f6d4bb2da1cea68a9224f43dd (diff) | |
download | waitress-33f68da9e2d45c228ce396fd4e9d1c3e24577f66.tar.gz |
Add HACKING.txt
- copied from Pyramid and modified.
-rw-r--r-- | HACKING.txt | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/HACKING.txt b/HACKING.txt new file mode 100644 index 0000000..99f96d8 --- /dev/null +++ b/HACKING.txt @@ -0,0 +1,218 @@ +Hacking on waitress +=================== + +Here are some guidelines for hacking on waitress. + + +Using a Development Checkout +---------------------------- + +You'll have to create a development environment to hack on waitress, using a +waitress 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 waitress repo on + GitHub. + + https://github.com/Pylons/waitress + +- Fork and clone the waitress repository to your GitHub account by clicking + the "Fork" button. + +- Clone your fork of waitress from your GitHub account to your local computer, + substituting your account username and specifying the destination as + "hack-on-waitress". + + $ cd ~ + $ git clone git@github.com:USERNAME/waitress.git hack-on-waitress + $ cd hack-on-waitress + # Configure remotes such that you can pull changes from the waitress + # repository into your local repository. + $ git remote add upstream https://github.com/Pylons/waitress.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 waitress: + + $ cd ~/hack-on-waitress + $ python3 -m venv env + + From here on in within these instructions, the ``~/hack-on-waitress/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-waitress/env`` command. + +- Install waitress from the checkout into the virtual environment, where the + current working directory is the ``waitress`` checkout directory. We will + install waitress in editable (development) mode as well as its testing + requirements. + + $ cd ~/hack-on-waitress + $ $VENV/bin/pip install -e ".[testing,docs]" + + +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-waitress + $ cd ~/hack-on-waitress + +- Check out a read-only copy of the waitress source: + + $ git clone git://github.com/Pylons/waitress.git . + + Alternatively, create a writeable fork on GitHub and clone it. + +Since waitress 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`` +(waitress's ``.gitconfig` ignores all top-level folders that start with ``env`` +specifically in our use case), and inside that a simple waitress 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 waitress: + +- 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, + and 3.6 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). + + +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. + +- 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 all tests for waitress on a single Python version from your + development virtual environment (See *Using a Development Checkout* above), + run ``nosetests``: + + $ $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 waitress.tests.test_module:ClassName.test_mytestname + + # run all tests in a class + $ $VENV/bin/nosetests waitress.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 waitress 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 waitress 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-waitress/ + $ /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 waitress/ + + 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 + + +Test Coverage +------------- + +- The codebase *must* have 100% test statement coverage after each commit. You + can test coverage via ``tox -e py2-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 waitress checkout directory, run ``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.txt`` + 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. |