Merge pull request #3389 from Pylons/remove-sudo-from-hacking

Michael Merickel

2018-10-16 a8b10ea3cb18143bb995a7637fc381c702c92d00

Merge pull request #3389 from Pylons/remove-sudo-from-hacking

Update HACKING.txt and contributing.md

 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

 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.