Permalink
Browse files

Improvements to developer experience.

 - 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.
  • Loading branch information...
jmchilton committed May 16, 2015
1 parent cdbf55a commit cc8abb6ffff4d7af586d7bea56a79e1d3a7a6917
Showing with 157 additions and 50 deletions.
  1. +92 −21 CONTRIBUTING.rst
  2. +51 −17 Makefile
  3. +0 −2 dev-requirements.txt
  4. +1 −1 docs/commands/shed_upload.rst
  5. +4 −7 docs/developing.rst
  6. +3 −0 scripts/pre-commit-lint
  7. +4 −0 scripts/pre-commit-lint-and-test
  8. +2 −2 tox.ini
@@ -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/
@@ -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
@@ -1,5 +1,3 @@
wheel==0.23.0

# For tests
flask

@@ -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).
@@ -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/>`_.
@@ -0,0 +1,3 @@
#!/bin/sh

make lint
@@ -0,0 +1,4 @@
#!/bin/sh

make lint
make quick-test
@@ -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 []

2 comments on commit cc8abb6

@peterjc

This comment has been minimized.

Copy link
Contributor

peterjc replied May 18, 2015

Does this mean tox should be added to dev-requirements.txt is it is used for running lint and flake8?

@jmchilton

This comment has been minimized.

Copy link
Member Author

jmchilton replied May 18, 2015

Yes - I believe it does (f463cf3) - thanks!

Please sign in to comment.