update development resources

davidism · davidism · commit 3c7625e8c024 · 2017-05-28T10:26:07.000-07:00
fix tox to test examples again
add detox tox env for faster testing
clean up makefile, add tox target
add extra group for installing dev requirements
clean up contributing doc, build with docs
expand issue template
add pull request template
diff --git a/.github/ISSUE_TEMPLATE.rst b/.github/ISSUE_TEMPLATE.rst
@@ -1,2 +1,33 @@
-The issue tracker is a tool to address bugs.
-Please use the #pocoo IRC channel on freenode or Stack Overflow for questions.
+**This issue tracker is a tool to address bugs in Flask itself.
+Please use the #pocoo IRC channel on freenode or Stack Overflow for general
+questions about using Jinja or issues not related to Jinja.**
+
+If you'd like to report a bug in Flask, fill out the template below. Provide
+any any extra information that may be useful / related to your problem.
+Ideally, create an [MCVE](http://stackoverflow.com/help/mcve), which helps us
+understand the problem and helps check that it is not caused by something in
+your code.
+
+---
+
+### Expected Behavior
+
+Tell us what should happen.
+
+```python
+Paste a minimal example that causes the problem.
+```
+
+### Actual Behavior
+
+Tell us what happens instead.
+
+```pytb
+Paste the full traceback if there was an exception.
+```
+
+### Environment
+
+* Python version:
+* Flask version:
+* Werkzeug version:
diff --git a/.github/PULL_REQUEST_TEMPLATE.rst b/.github/PULL_REQUEST_TEMPLATE.rst
@@ -0,0 +1,16 @@
+Describe what this patch does to fix the issue.
+
+Link to any relevant issues or pull requests.
+
+<!--
+Commit checklist:
+
+* add tests that fail without the patch
+* ensure all tests pass with ``pytest``
+* add documentation to the relevant docstrings or pages
+* add ``versionadded`` or ``versionchanged`` directives to relevant docstrings
+* add a changelog entry if this patch changes code
+
+Tests, coverage, and docs will be run automatically when you submit the pull
+request, but running them yourself can save time.
+-->
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -1,46 +1,75 @@
-==========================
 How to contribute to Flask
 ==========================
 
-Thanks for considering contributing to Flask.
+Thank you for considering contributing to Flask!
 
 Support questions
-=================
+-----------------
+
+Please, don't use the issue tracker for this. Use one of the following
+resources for questions about your own code:
+
+* The IRC channel ``#pocoo`` on FreeNode.
+* The IRC channel ``#python`` on FreeNode for more general questions.
+* The mailing list flask@python.org for long term discussion or larger issues.
+* Ask on `Stack Overflow`_. Search with Google first using:
+  ``site:stackoverflow.com flask {search term, exception message, etc.}``
 
-Please, don't use the issue tracker for this. Check whether the ``#pocoo`` IRC
-channel on Freenode can help with your issue. If your problem is not strictly
-Werkzeug or Flask specific, ``#python`` is generally more active.
-`Stack Overflow <https://stackoverflow.com/>`_ is also worth considering.
+.. _Stack Overflow: https://stackoverflow.com/questions/tagged/flask?sort=linked
 
 Reporting issues
-================
+----------------
 
-- Under which versions of Python does this happen? This is even more important
-  if your issue is encoding related.
+- Describe what you expected to happen.
+- If possible, include a `minimal, complete, and verifiable example`_ to help
+  us identify the issue. This also helps check that the issue is not with your
+  own code.
+- Describe what actually happened. Include the full traceback if there was an
+  exception.
+- List your Python, Flask, and Werkzeug versions. If possible, check if this
+  issue is already fixed in the repository.
 
-- Under which versions of Werkzeug does this happen? Check if this issue is
-  fixed in the repository.
+.. _minimal, complete, and verifiable example: https://stackoverflow.com/help/mcve
 
 Submitting patches
-==================
+------------------
 
 - Include tests if your patch is supposed to solve a bug, and explain
   clearly under which circumstances the bug happens. Make sure the test fails
   without your patch.
-
-- Try to follow `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_, but you
-  may ignore the line-length-limit if following it would make the code uglier.
+- Try to follow `PEP8`_, but you may ignore the line length limit if following
+  it would make the code uglier.
 
 First time setup
-----------------
+~~~~~~~~~~~~~~~~
 
 - Download and install the `latest version of git`_.
-- Configure git with your `username`_ and `email`_.
+- Configure git with your `username`_ and `email`_::
+
+        git config --global user.name 'your name'
+        git config --global user.email 'your email'
+
 - Make sure you have a `GitHub account`_.
 - Fork Flask to your GitHub account by clicking the `Fork`_ button.
-- `Clone`_ your GitHub fork locally.
-- Add the main repository as a remote to update later.
-  ``git remote add pallets https://github.com/pallets/flask``
+- `Clone`_ your GitHub fork locally::
+
+        git clone https://github.com/{username}/flask
+        cd flask
+
+- Add the main repository as a remote to update later::
+
+        git remote add pallets https://github.com/pallets/flask
+        git fetch pallets
+
+- Create a virtualenv::
+
+        python3 -m venv env
+        . env/bin/activate
+        # or "env\Scripts\activate" on Windows
+
+- Install Flask in editable mode with development dependencies::
+
+        pip install -e ".[dev]"
 
 .. _GitHub account: https://github.com/join
 .. _latest version of git: https://git-scm.com/downloads
@@ -50,7 +79,7 @@ First time setup
 .. _Clone: https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork
 
 Start coding
-------------
+~~~~~~~~~~~~
 
 - Create a branch to identify the issue you would like to work on (e.g.
   ``2287-dry-test-suite``)
@@ -68,98 +97,70 @@ Start coding
 
 .. _contributing-testsuite:
 
-Running the testsuite
----------------------
+Running the tests
+~~~~~~~~~~~~~~~~~
 
-You probably want to set up a `virtualenv
-<https://virtualenv.readthedocs.io/en/latest/index.html>`_.
+Run the basic test suite with::
 
-The minimal requirement for running the testsuite is ``pytest``.  You can
-install it with::
+    pytest
 
-    pip install pytest
+This only runs the tests for the current environment. Whether this is relevant
+depends on which part of Flask you're working on. Travis-CI will run the full
+suite when you submit your pull request.
 
-Clone this repository::
+The full test suite takes a long time to run because it tests multiple
+combinations of Python and dependencies. You need to have Python 2.6, 2.7, 3.3,
+3.4, 3.5 3.6, and PyPy 2.7 installed to run all of the environments. Then run::
 
-    git clone https://github.com/pallets/flask.git
-
-Install Flask as an editable package using the current source::
-
-    cd flask
-    pip install --editable .
-
-Running the testsuite
----------------------
-
-The minimal requirement for running the testsuite is ``pytest``.  You can
-install it with::
-
-    pip install pytest
-
-Then you can run the testsuite with::
-
-    pytest tests/
-
-**Shortcut**: ``make test`` will ensure ``pytest`` is installed, and run it.
-
-With only pytest installed, a large part of the testsuite will get skipped
-though.  Whether this is relevant depends on which part of Flask you're working
-on.  Travis is set up to run the full testsuite when you submit your pull
-request anyways.
-
-If you really want to test everything, you will have to install ``tox`` instead
-of ``pytest``. You can install it with::
-
-    pip install tox
-
-The ``tox`` command will then run all tests against multiple combinations
-Python versions and dependency versions.
-
-**Shortcut**: ``make tox-test`` will ensure ``tox`` is installed, and run it.
+    tox
 
 Running test coverage
----------------------
-Generating a report of lines that do not have unit test coverage can indicate where
-to start contributing.  ``pytest`` integrates with ``coverage.py``, using the ``pytest-cov``
-plugin.  This assumes you have already run the testsuite (see previous section)::
+~~~~~~~~~~~~~~~~~~~~~
 
-    pip install pytest-cov
+Generating a report of lines that do not have test coverage can indicate
+where to start contributing. Run ``pytest`` using ``coverage`` and generate a
+report on the terminal and as an interactive HTML document::
 
-After this has been installed, you can output a report to the command line using this command::
+    coverage run -m pytest
+    coverage report
+    coverage html
+    # then open htmlcov/index.html
 
-    pytest --cov=flask tests/
+Read more about `coverage <https://coverage.readthedocs.io>`_.
 
-Generate a HTML report can be done using this command::
+Running the full test suite with ``tox`` will combine the coverage reports
+from all runs.
 
-    pytest --cov-report html --cov=flask tests/
+``make`` targets
+~~~~~~~~~~~~~~~~
 
-Full docs on ``coverage.py`` are here: https://coverage.readthedocs.io
+Flask provides a ``Makefile`` with various shortcuts. They will ensure that
+all dependencies are installed.
 
-**Shortcut**: ``make cov`` will ensure ``pytest-cov`` is installed, run it, display the results, *and* save the HTML report.
+- ``make test`` runs the basic test suite with ``pytest``
+- ``make cov`` runs the basic test suite with ``coverage``
+- ``make test-all`` runs the full test suite with ``tox``
+- ``make docs`` builds the HTML documentation
 
+Caution: zero-padded file modes
+-------------------------------
 
-Caution
-=======
-pushing
--------
-This repository contains several zero-padded file modes that may cause issues when pushing this repository to git hosts other than github. Fixing this is destructive to the commit history, so we suggest ignoring these warnings. If it fails to push and you're using a self-hosted git service like Gitlab, you can turn off repository checks in the admin panel.
+This repository contains several zero-padded file modes that may cause issues
+when pushing this repository to git hosts other than GitHub. Fixing this is
+destructive to the commit history, so we suggest ignoring these warnings. If it
+fails to push and you're using a self-hosted git service like GitLab, you can
+turn off repository checks in the admin panel.
 
-
-cloning
--------
-The zero-padded file modes files above can cause issues while cloning, too. If you have
-
-::
+These files can also cause issues while cloning. If you have ::
 
     [fetch]
     fsckobjects = true
 
-or
-
-::
+or ::
 
     [receive]
     fsckObjects = true
 
-
-set in your git configuration file, cloning this repository will fail. The only solution is to set both of the above settings to false while cloning, and then setting them back to true after the cloning is finished.
+set in your git configuration file, cloning this repository will fail. The only
+solution is to set both of the above settings to false while cloning, and then
+setting them back to true after the cloning is finished.
diff --git a/Makefile b/Makefile
@@ -1,24 +1,35 @@
-.PHONY: clean-pyc ext-test test tox-test test-with-mem upload-docs docs audit
+.PHONY: all install-dev test coverage cov test-all tox docs audit release clean-pyc upload-docs ebook
 
-all: clean-pyc test
+all: test
 
-test:
-	pip install -r test-requirements.txt
-	tox -e py-release
+install-dev:
+	pip install -q -e .[dev]
 
-cov:
-	pip install -r test-requirements.txt -q
-	FLASK_DEBUG= py.test --cov-report term --cov-report html --cov=flask --cov=examples tests examples
+test: clean-pyc install-dev
+	pytest
+
+coverage: clean-pyc install-dev
+	pip install -q -e .[test]
+	coverage run -m pytest
+	coverage report
+	coverage html
+
+cov: coverage
+
+test-all: install-dev
+	tox
+
+tox: test-all
+
+docs: clean-pyc install-dev
+	$(MAKE) -C docs html
 
 audit:
 	python setup.py audit
 
 release:
 	python scripts/make-release.py
 
-ext-test:
-	python tests/flaskext_test.py --browse
-
 clean-pyc:
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
@@ -40,6 +51,3 @@ ebook:
 	@echo 'Requires X-forwarding for Qt features used in conversion (ssh -X).'
 	@echo 'Do not mind "Invalid value for ..." CSS errors if .mobi renders.'
 	ssh -X pocoo.org ebook-convert /var/www/flask.pocoo.org/docs/flask-docs.epub /var/www/flask.pocoo.org/docs/flask-docs.mobi --cover http://flask.pocoo.org/docs/_images/logo-full.png --authors 'Armin Ronacher'
-
-docs:
-	$(MAKE) -C docs html
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
@@ -59,3 +59,4 @@ Design notes, legal information and changelog are here for the interested.
    upgrading
    changelog
    license
+   contributing
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst
diff --git a/setup.py b/setup.py
@@ -48,14 +48,12 @@ def hello():
 import ast
 from setuptools import setup
 
-
 _version_re = re.compile(r'__version__\s+=\s+(.*)')
 
 with open('flask/__init__.py', 'rb') as f:
     version = str(ast.literal_eval(_version_re.search(
         f.read().decode('utf-8')).group(1)))
 
-
 setup(
     name='Flask',
     version=version,
@@ -76,6 +74,17 @@ def hello():
         'itsdangerous>=0.21',
         'click>=4.0',
     ],
+    extras_require={
+        'dev': [
+            'blinker',
+            'greenlet',
+            'pytest>=3',
+            'coverage',
+            'tox',
+            'sphinx',
+            'sphinxcontrib-log-cabinet'
+        ],
+    },
     classifiers=[
         'Development Status :: 4 - Beta',
         'Environment :: Web Environment',
diff --git a/tox.ini b/tox.ini
