diff options
author | Steve Piercy <web@stevepiercy.com> | 2018-05-20 13:48:31 -0700 |
---|---|---|
committer | Steve Piercy <web@stevepiercy.com> | 2018-05-20 13:48:31 -0700 |
commit | 184f604cc558fa977a041b0cae2591fe0f2b79f6 (patch) | |
tree | a293e8a374e973f93b8e142c6339cc8d45d24269 | |
parent | 675ef5daa68abbe9f568d06f6476f74c8a5940c7 (diff) | |
download | waitress-184f604cc558fa977a041b0cae2591fe0f2b79f6.tar.gz |
Delete HACKING.txt
- because it duplicates contributing.md and its links to pylonsproject.org
-rw-r--r-- | HACKING.txt | 218 |
1 files changed, 0 insertions, 218 deletions
diff --git a/HACKING.txt b/HACKING.txt deleted file mode 100644 index 99f96d8..0000000 --- a/HACKING.txt +++ /dev/null @@ -1,218 +0,0 @@ -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. |