From a8b10ea3cb18143bb995a7637fc381c702c92d00 Mon Sep 17 00:00:00 2001
From: Michael Merickel <github@m.merickel.org>
Date: Tue, 16 Oct 2018 02:56:45 +0200
Subject: [PATCH] Merge pull request #3389 from Pylons/remove-sudo-from-hacking
---
HACKING.txt | 155 +++++++-------------------------------
contributing.md | 69 ----------------
2 files changed, 30 insertions(+), 194 deletions(-)
diff --git a/HACKING.txt b/HACKING.txt
index 032d98f..8129e9c 100644
--- a/HACKING.txt
+++ b/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
diff --git a/contributing.md b/contributing.md
index aa0f107..734f014 100644
--- a/contributing.md
+++ b/contributing.md
@@ -22,71 +22,6 @@
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 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:<username>/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.
--
Gitblit v1.9.3