Improvements to developer experience.

jmchilton · jmchilton · commit cc8abb6ffff4 · 2015-05-16T13:03:47.000-04:00
- Add more information to CONTRIBUTING.rst - including information on tox and running specific tests. - Add new quick-test make target for running the fatest tests quickly (and documentation). - Add new tox make target for running specific tests with tox (and documentation). - Add new _open-docs make target open pre-existing docs locally. - Modify lint make target to lint through tox to verify both Python 2 and Python 3 syntax. - Add new flake8 make target corresponding to the old lint target. - Add Makefile targets for installing pre-commit git hooks - one that lints and one that lints and runs the new quick-test target (and documentation). - Fix dev-requirements.txt which had a duplicated wheel entry. - General Makefile refactoring and documentation improvements. Closes #209.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -36,8 +36,8 @@ is open to whoever wants to implement it.
 Implement Features
 ~~~~~~~~~~~~~~~~~~
 
-Look through the GitHub issues for features. Anything tagged with "feature"
-is open to whoever wants to implement it.
+Look through the GitHub issues for features. Anything tagged with
+"enhancement" is open to whoever wants to implement it.
 
 Write Documentation
 ~~~~~~~~~~~~~~~~~~~
@@ -70,9 +70,7 @@ Ready to contribute? Here's how to set up `planemo` for local development.
 
 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
 
-    $ mkvirtualenv planemo
-    $ cd planemo/
-    $ python setup.py develop
+    $ make setup-venv
 
 4. Create a branch for local development::
 
@@ -81,18 +79,17 @@ Ready to contribute? Here's how to set up `planemo` for local development.
    Now you can make your changes locally.
 
 5. When you're done making changes, check that your changes pass ``flake8``
-and the tests::
-
-    $ flake8 planemo tests
-    $ python setup.py test
-
-To get ``flake8``, just ``pip install`` them into your virtualenv.
-
-.. including testing other Python versions with tox
-..    $ python setup.py test
-..    $ tox
-..
-..   To get flake8 and tox, just pip install them into your virtualenv.
+   and the tests
+   
+   ::
+
+       $ make lint
+       $ make test
+   
+   If the modification doesn't affect code that configures and runs Galaxy - 
+   skipping a couple tests that will cause Galaxy and its dependencies to be
+   downloaded results in a significant speed up. This subset of tests can be
+   run with ``make quick-test``.
 
 6. Commit your changes and push your branch to GitHub::
 
@@ -113,7 +110,81 @@ Before you submit a pull request, check that it meets these guidelines:
    https://travis-ci.org/galaxyproject/planemo/pull_requests
    and make sure that the tests pass for all supported Python versions.
 
-.. Tips
-.. ----
-.. To run a subset of tests::
-..    $ python -m unittest tests.test_planemo
+Tips
+----
+
+To run a subset of tests::
+
+    % make tox ENV=py27 ARGS='--tests tests/test_shed_upload.py'
+
+This will use Tox_ to run the specified tests using Python 2.7. ``ENV`` here
+can be used to specify different Python version (e.g. ``py26``, ``py27``,
+``py34``). Python 3.4 is a work in progress. 
+
+Even more granularity is also possible by specifying specific test methods.::
+
+    make tox ENV=py27 ARGS='--tests tests/test_shed_upload.py:ShedUploadTestCase.test_tar_from_git'
+
+
+``tox`` can be used to run tests directly also (use ``. .venv/bin/activate``
+to ensure it is on your ``PATH``).
+
+::
+
+    tox -e py27 -- --tests tests/test_shed_upload.py
+
+Tox_ itself is configured to wrap nose_. One can skip Tox_ and run
+``nosetests`` directly.
+
+::
+
+    nosetests tests/test_shed_upload.py
+
+Tox_
+~~~~~~~~~~~
+
+Tox_ is a tool to automate testing across different Python versions. The
+``tox`` executable can be supplied with a ``-e`` argument to specify a
+testing environment. Planemo defines the following environments:
+
+``py27-lint``
+    Lint the planemo code using Python 2.7.
+
+``py34-lint``
+    Lint the planemo code using Python 3.4 (also ensures valid Python 3
+    syntax).
+
+``py27-lint-readme``
+    Lint the README reStructuredText.
+
+``py26``
+    Run planemo tests in Python 2.6.
+
+``py27``
+    Run planemo tests in Python 2.7.
+
+``py34``
+    Run planemo tests in Python 3.4 (not currently working).
+
+
+Pre-commit Hooks
+~~~~~~~~~~~~~~~~~~~~~
+
+Planemo pull requests are automatically linted and tested using `TravisCI
+<https://travis-ci.org/galaxyproject/planemo>`__. A git pre-commit `hook
+<http://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks>`__ can be setup
+to lint and/or test Planemo before committing to catch problems that would
+be detected by TravisCI as early as possible.
+
+The following command will install a pre-commit hook that lints the Planemo
+code::
+
+    make setup-git-hook-lint
+
+To also run the faster planemo tests, the following command can be used to 
+setup a more rigorous pre-commit hook::
+
+    make setup-git-hook-lint-and-test
+
+.. _Tox: https://tox.readthedocs.org/en/latest/
+.. _nose: https://nose.readthedocs.org/en/latest/
diff --git a/Makefile b/Makefile
@@ -1,3 +1,14 @@
+# Default tests run with make test and make quick-tests
+NOSE_TESTS=tests planemo
+# Default environment for make tox
+ENV?=py27
+# Extra arguments supplied to tox command
+ARGS?=
+# Location of virtualenv used for development.
+VENV=.venv
+# Source virtualenv to execute command (flake8, sphinx, twine, etc...)
+IN_VENV=if [ -f $(VENV)/bin/activate ]; then . $(VENV)/bin/activate; fi;
+
 .PHONY: clean-pyc clean-build docs clean
 
 help:
@@ -6,13 +17,19 @@ help:
 	@echo "clean-pyc - remove Python file artifacts"
 	@echo "clean-test - remove test and coverage artifacts"
 	@echo "setup-venv - setup a development virutalenv in current directory."
-	@echo "lint - check style with flake8"
+	@echo "lint - check style using tox and flake8 for Python 2 and Python 3"
 	@echo "lint-readme - check README formatting for PyPI"
-	@echo "test - run tests quickly with the default Python"
+	@echo "flake8 - check style using flake8 for current Python (faster than lint)"
+	@echo "test - run tests with the default Python (faster than tox)"
+	@echo "quick-test - run quickest tests with the default Python"
 	@echo "coverage - check code coverage quickly with the default Python"
 	@echo "docs - generate Sphinx HTML documentation, including API docs"
-	@echo "release - package and upload a release"
+	@echo "open-docs - generate Sphinx HTML documentation and open in browser"
+	@echo "open-rtd - open docs on readthedocs.org"
+	@echo "open-project - open project on github"
+	@echo "release - package, review, and upload a release"
 	@echo "dist - package"
+	@echo "update-extern - update external artifacts copied locally"
 
 clean: clean-build clean-pyc clean-test
 
@@ -33,17 +50,32 @@ clean-test:
 	rm -fr htmlcov/
 
 setup-venv:
-	if [ -f .venv ]; then virtualenv .venv; fi;
-	. .venv/bin/activate && pip install -r requirements.txt && pip install -r dev-requirements.txt
+	if [ -f $(VENV) ]; then virtualenv $(VENV); fi;
+	$(IN_VENV) pip install -r requirements.txt && pip install -r dev-requirements.txt
+
+setup-git-hook-lint:
+	cp scripts/pre-commit-lint .git/hooks/pre-commit
+
+setup-git-hook-lint-and-test:
+	cp scripts/pre-commit-lint-and-test .git/hooks/pre-commit
+
+flake8:
+	$(IN_VENV) flake8 --max-complexity 11 planemo tests
 
 lint:
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; flake8 --max-complexity 11 planemo tests
+	$(IN_VENV) tox -e py27-lint && tox -e py34-lint
 
 lint-readme:
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; python setup.py check -r -s
+	$(IN_VENV) python setup.py check -r -s
 
 test:
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; nosetests tests planemo
+	$(IN_VENV) nosetests $(NOSE_TESTS)
+
+quick-test:
+	$(IN_VENV) PLANEMO_SKIP_GALAXY_TESTS=1 nosetests $(NOSE_TESTS)
+
+tox:
+	$(IN_VENV) tox -e $(ENV) -- $(ARGS)
 
 coverage:
 	coverage run --source planemo setup.py test
@@ -55,27 +87,29 @@ docs:
 	rm -f docs/planemo.rst
 	rm -f docs/planemo_ext.rst
 	rm -f docs/modules.rst
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; sphinx-apidoc -f -o docs/ planemo_ext planemo_ext/galaxy/eggs
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; sphinx-apidoc -f -o docs/ planemo
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; python scripts/commands_to_rst.py
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; $(MAKE) -C docs clean
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; $(MAKE) -C docs html
+	$(IN_VENV) sphinx-apidoc -f -o docs/ planemo_ext planemo_ext/galaxy/eggs
+	$(IN_VENV) sphinx-apidoc -f -o docs/ planemo
+	$(IN_VENV) python scripts/commands_to_rst.py
+	$(IN_VENV) $(MAKE) -C docs clean
+	$(IN_VENV) $(MAKE) -C docs html
 
-open-docs: docs
+_open-docs:
 	open docs/_build/html/index.html || xdg-open docs/_build/html/index.html
 
+open-docs: docs _open-docs
+
 open-rtd: docs
 	open https://planemo.readthedocs.org || xdg-open https://planemo.readthedocs.org
 
 open-project:
 	open https://github.com/galaxyproject/planemo || xdg-open https://github.com/galaxyproject/planemo
 
 dist: clean
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; python setup.py sdist bdist_egg bdist_wheel
+	$(IN_VENV) python setup.py sdist bdist_egg bdist_wheel
 	ls -l dist
 
 release-test: dist
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; twine upload -r test dist/*
+	$(IN_VENV) twine upload -r test dist/*
 	open https://testpypi.python.org/pypi/planemo || xdg-open https://testpypi.python.org/pypi/planemo
 
 release: release-test
@@ -84,7 +118,7 @@ release: release-test
 	done ; \
 	[ $$CONTINUE = "y" ] || [ $$CONTINUE = "Y" ] || (echo "Exiting."; exit 1;)
 	@echo "Releasing"
-	if [ -f .venv/bin/activate ]; then . .venv/bin/activate; fi; twine upload dist/*
+	$(IN_VENV) twine upload dist/*
 
 update-extern:
 	sh scripts/update_extern.sh
diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -1,5 +1,3 @@
-wheel==0.23.0
-
 # For tests
 flask
 
diff --git a/docs/commands/shed_upload.rst b/docs/commands/shed_upload.rst
@@ -17,7 +17,7 @@ Handle possible recursion through paths for uploading files to a toolshed
 **Options**::
 
 
-      --message TEXT               Commit message for tool shed upload.
+      -m, --message TEXT           Commit message for tool shed upload.
       --owner TEXT                 Tool Shed repository owner (username).
       --name TEXT                  Tool Shed repository name (defaults to the
                                    inferred tool directory name).
diff --git a/docs/developing.rst b/docs/developing.rst
@@ -1,11 +1,8 @@
-==========
-Developing
-==========
-
-This section contains documentation for the maintainers of planemo.
-
+==================
 Release Checklist
------------------
+==================
+
+This page describes the process of releasing new versions of Planemo.
 
 This release checklist is based on the `Pocoo Release Management Workflow
 <http://www.pocoo.org/internal/release-management/>`_.
diff --git a/scripts/pre-commit-lint b/scripts/pre-commit-lint
@@ -0,0 +1,3 @@
+#!/bin/sh
+
+make lint
diff --git a/scripts/pre-commit-lint-and-test b/scripts/pre-commit-lint-and-test
@@ -0,0 +1,4 @@
+#!/bin/sh
+
+make lint
+make quick-test
diff --git a/tox.ini b/tox.ini
@@ -1,7 +1,7 @@
-# TODO: add py34-lint , py34 to envlist
+# TODO: py34 to envlist
 # TODO: implement doc linting
 [tox]
-envlist = py27-lint, py27-lint-readme, py26, py27
+envlist = py34-lint, py27-lint, py27-lint-readme, py26, py27
 
 [testenv]
 commands = {envpython} setup.py nosetests []

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-wheel==0.23.0`
`2`		`-`
`3`	`1`	`# For tests`
`4`	`2`	`flask`
`5`	`3`