From 8cc7834c93f71ac87a493a3018c32a75c3cca390 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 15 Oct 2018 14:34:34 -0700 Subject: 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 | 155 +++++++++++------------------------------------------------- 1 file changed, 28 insertions(+), 127 deletions(-) diff --git a/HACKING.txt b/HACKING.txt index 032d98f30..8129e9c16 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -7,79 +7,13 @@ Here are some guidelines for hacking on Pyramid. 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: $ mkdir ~/hack-on-pyramid @@ -91,22 +25,6 @@ way to get going. 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 @@ platform, that caveat should be spelled out clearly in *its* documentation 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 @@ Running Tests # 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 -- cgit v1.2.3 From cf359de45d8d23c292aa0b5fd04f33d47400914e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 15 Oct 2018 14:41:03 -0700 Subject: Remove documentation building section, now that we got a tox env for that --- contributing.md | 67 +-------------------------------------------------------- 1 file changed, 1 insertion(+), 66 deletions(-) diff --git a/contributing.md b/contributing.md index aa0f10761..8eac9fb2d 100644 --- a/contributing.md +++ b/contributing.md @@ -24,69 +24,4 @@ one or two development branches are actively maintained. ## Prerequisites -Follow the instructions in HACKING.txt for your version or branch located in -the [root of the Pyramid repository](https://github.com/Pylons/pyramid/) to -install Pyramid and the tools needed to run its tests and build its -documentation. - -## Building documentation for a Pylons Project project - -*Note:* These instructions might not work for Windows users. Suggestions to -improve the process for Windows users are welcome by submitting an issue or a -pull request. Windows users may find it helpful to follow the guide [Installing -Pyramid on a Windows -System](https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.html#installing-pyramid-on-a-windows-system). - -1. Fork the repo on GitHub by clicking the [Fork] button. -2. Clone your fork into a workspace on your local machine. - - git clone git@github.com:/pyramid.git - -3. Change directories into the cloned repository - - cd pyramid - -4. Add a git remote "upstream" for the cloned fork. - - git remote add upstream git@github.com:Pylons/pyramid.git - -5. Create a virtual environment and set an environment variable as instructed in the - [prerequisites](https://github.com/Pylons/pyramid/blob/master/HACKING.txt#L48-L56). - - # Mac and Linux - $ export VENV=~/hack-on-pyramid/env - - # Windows - set VENV=c:\hack-on-pyramid\env - -6. Install `tox` into your virtual environment. - - $ $VENV/bin/pip install tox - -7. Try to build the docs in your workspace. - - $ $VENV/bin/tox -e docs - - When the build finishes, you'll find HTML documentation rendered in - `.tox/docs/html`. An `epub` version will be in `.tox/docs/epub`. And the - result of the tests that are run on the documentation will be in - `.tox/docs/doctest`. - -8. From this point forward, follow the typical [git - workflow](https://help.github.com/articles/what-is-a-good-git-workflow/). - *Always* start by pulling from the upstream to get the most current changes. - - git pull upstream master - -9. Make a branch, make changes to the docs, and rebuild them as indicated above. - -10. Once you are satisfied with your changes and the documentation builds - successfully without errors or warnings, then git commit and push them to - your "origin" repository on GitHub. - - git commit -m "commit message" - git push -u origin --all # first time only, subsequent can be just 'git push'. - -11. Create a [pull request](https://help.github.com/articles/using-pull-requests/). - -12. Repeat the process starting from Step 8. +Follow the instructions in [HACKING.txt](https://github.com/Pylons/pyramid/blob/master/HACKING.txt) to install Pyramid and the tools needed to run its tests and build its documentation. -- cgit v1.2.3 From 125f0bddfead5ef65f96ca33e894804e693efbd5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 15 Oct 2018 15:48:17 -0700 Subject: Rename section from Prerequisites to Developing --- contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index 8eac9fb2d..734f014f5 100644 --- a/contributing.md +++ b/contributing.md @@ -22,6 +22,6 @@ Git branches and their purpose and status at the time of this writing are listed Older branches are not actively maintained. In general, two stable branches and one or two development branches are actively maintained. -## Prerequisites +## Developing Follow the instructions in [HACKING.txt](https://github.com/Pylons/pyramid/blob/master/HACKING.txt) to install Pyramid and the tools needed to run its tests and build its documentation. -- cgit v1.2.3