Switch to pytest; drop (dev-)requirements.txt

pyeve · May 7, 2018 · cfe8d21 · cfe8d21
1 parent 77f28d7
commit cfe8d21
Show file tree

Hide file tree

Showing 8 changed files with 189 additions and 257 deletions.
diff --git a/CHANGES b/CHANGES
@@ -8,6 +8,12 @@ Development
 
 Version 0.8
 ~~~~~~~~~~~
+- Dev: Switch to pytest as the standard testing tool.
+- Dev: Drop ``requiments.txt`` and ``dev-requirements.txt``. Use ``pip install
+  -e .[dev|tests|docs]`` instead.
+- Docs: Comprehensive rewrite of the Contributing page. 
+- Docs: Drop the testing page; merge its contents with the Contributing
+  page.
 - Flask requirement set to >=1.0. Closes #1111.
 - Python 2.6 and Python 3.3 are no longer supported.
 - Tests: finally acknowledge the existence of modern APIs for both Mongo and

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -1,50 +1,167 @@
-How to Contribute
-#################
+How to contribute
+=================
 
 Contributions are welcome! Not familiar with the codebase yet? No problem!
 There are many ways to contribute to open source projects: reporting bugs,
 helping with the documentation, spreading the word and of course, adding
 new features and patches. 
 
-Getting Started
----------------
-#. Make sure you have a GitHub_ account.
-#. Open a `new issue`_, assuming one does not already exist.
-#. Clearly describe the issue including steps to reproduce when it is a bug.
-
-Making Changes
---------------
-* Fork_ the repository on GitHub.
-* Create a topic branch from where you want to base your work.
-* This is usually the ``master`` branch. 
-* Make commits of logical units (if needed rebase your feature branch before
-  submitting it).
-* Check for unnecessary whitespace with ``git diff --check`` before committing.
-* Make sure your commit messages are in the `proper format`_.
-* If your commit fixes an open issue, reference it in the commit message (#15).
-* Make sure your code conforms to PEP8_ (we're using flake8_ for PEP8 and extra checks).
-* Make sure you have added the necessary tests for your changes.
-* Run all the tests to assure nothing else was accidentally broken.
-* Run again the entire suite via tox_ to check your changes against multiple
-  python versions. ``pip install tox; tox``
-* Don't forget to add yourself to AUTHORS_.
-
-These guidelines also apply when helping with documentation (actually,
-for typos and minor additions you might choose to `fork and
-edit`_). See also the `running the tests`_ section in the official
-documentation.
-
-Submitting Changes
+Support questions
+-----------------
+
+Please, don't use the issue tracker for this. Use one of the following
+resources for questions about your own code:
+
+* Ask on `Stack Overflow`_. Search with Google first using: ``site:stackoverflow.com eve {search term, exception message, etc.}``
+* The `mailing list`_ is intended to be a low traffic resource for both developers/contributors and API maintainers looking for help or requesting feedback. 
+* The IRC channel ``#python-eve`` on FreeNode.
+
+.. _Stack Overflow: https://stackoverflow.com/questions/tagged/eve?sort=linked
+.. _`mailing list`: https://groups.google.com/forum/#!forum/python-eve
+
+Reporting issues
+----------------
+
+- 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 and Eve versions. If possible, check if this issue is
+  already fixed in the repository.
+
+.. _minimal, complete, and verifiable example: https://stackoverflow.com/help/mcve
+
+Submitting patches
 ------------------
-* Push your changes to a topic branch in your fork of the repository.
-* Submit a `Pull Request`_.
-* Wait for maintainer feedback.
 
-Join us on IRC
---------------
-If you're interested in contributing to the Eve project or have questions
-about it come join us in our little #python-eve channel on irc.freenode.net.
-It's comfy and cozy over there.
+- 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.
+- Follow `PEP8`_. CI will reject a change that does not conform to the
+  guidelines.
+
+First time setup
+~~~~~~~~~~~~~~~~
+
+- Download and install the `latest version of git`_.
+- 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 Eve to your GitHub account by clicking the `Fork`_ button.
+- `Clone`_ your GitHub fork locally::
+
+        git clone https://github.com/{username}/eve
+        cd eve
+
+- Add the main repository as a remote to update later::
+
+        git remote add pyeve https://github.com/pyeve/eve
+        git fetch pyeve
+
+- Create a virtualenv::
+
+        python3 -m venv env
+        . env/bin/activate
+        # or "env\Scripts\activate" on Windows
+
+- Install Eve 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
+.. _username: https://help.github.com/articles/setting-your-username-in-git/
+.. _email: https://help.github.com/articles/setting-your-email-in-git/
+.. _Fork: https://github.com/pallets/flask/fork
+.. _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.
+  ``fix_for_#1280``)
+- Using your favorite editor, make your changes, `committing as you go`_.
+- Follow `PEP8`_.
+- Include tests that cover any code changes you make. Make sure the test fails
+  without your patch. `Run the tests. <contributing-testsuite_>`_.
+- Push your commits to GitHub and `create a pull request`_.
+- Celebrate 🎉
+
+.. _committing as you go: http://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes
+.. _PEP8: https://pep8.org/
+.. _create a pull request: https://help.github.com/articles/creating-a-pull-request/
+
+.. _contributing-testsuite:
+
+Running the tests
+~~~~~~~~~~~~~~~~~
+
+Run the basic test suite with::
+
+    pytest
+
+If you want you can run a single module, say the ``methods`` suite::
+
+   pytest eve/tests/methods/
+
+Or, to run only the ``get`` tests::
+
+   pytest eve/tests/methods/get.py
+
+You can also choose to just run a single class::
+
+    pytest eve/tests/methods/get.py::TestGet
+
+Or even a single test::
+
+   pytest eve/tests/methods/get.py::TestGet::test_get_emtpy_resource
+
+You can also collect tests by keyword::
+
+   pytest -k auth
+
+These only runs the tests for the current environment. Whether this is relevant
+depends on which part of Eve you're working on. Travis-CI will run the full
+suite when you submit your pull request.
+
+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.7, 3.4,
+3.5, 3.6, and PyPy installed to run all of the environments. Then run::
+
+    tox
+
+Or, if you want to only run your tests against a specific Python environment::
+
+    tox -e py36
+    # py27 = Python 2.7
+    # py34 = Python 3.4
+    # py35 = Python 3.5
+    # py36 = Python 3.6
+    # pypy + PyPy
+
+Rate limiting tests
+~~~~~~~~~~~~~~~~~~~
+While there are no test requirements for most of the suite, please be advised
+that in order to execute the :ref:`ratelimiting` tests you need a running
+Redis_ server. The Rate-Limiting tests are silently skipped if any of the two
+conditions are not met. 
+
+Building the docs
+~~~~~~~~~~~~~~~~~
+
+Build the docs in the ``docs`` directory using Sphinx::
+
+    cd docs
+    make html BUILDDIR=_build
+
+Open ``_build/html/index.html`` in your browser to view the docs.
+
+Read more about `Sphinx <http://www.sphinx-doc.org>`_.
 
 First time contributor?
 -----------------------
@@ -54,27 +171,25 @@ Don't know where to start?
 --------------------------
 There are usually several TODO comments scattered around the codebase, maybe
 check them out and see if you have ideas, or can help with them. Also, check
-the `open issues`_ in case there's something that sparks your interest (there's
-also a special ``contributor friendly`` label flagging some interesting feature
-requests). And what about documentation?  I suck at English so if you're fluent
-with it (or notice any typo and/or mistake), why not help with that? In any
-case, other than GitHub help_ pages, you might want to check this excellent
-`Effective Guide to Pull Requests`_
+the `open issues`_ in case there's something that sparks your interest. And
+what about documentation? I suck at English, so if you're fluent with it (or
+notice any typo and/or mistake), why not help with that? In any case, other
+than GitHub help_ pages, you might want to check this excellent `Effective
+Guide to Pull Requests`_
 
 .. _`the repository`: http://github.com/pyeve/eve
 .. _AUTHORS: https://github.com/pyeve/eve/blob/master/AUTHORS
 .. _`open issues`: https://github.com/pyeve/eve/issues
 .. _`new issue`: https://github.com/pyeve/eve/issues/new
 .. _GitHub: https://github.com/
-.. _Fork: https://help.github.com/articles/fork-a-repo
 .. _`proper format`: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
-.. _PEP8: http://www.python.org/dev/peps/pep-0008/
 .. _flake8: http://flake8.readthedocs.org/en/latest/
 .. _tox: http://tox.readthedocs.org/en/latest/
 .. _help: https://help.github.com/
 .. _`Effective Guide to Pull Requests`: http://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github/
 .. _`fork and edit`: https://github.com/blog/844-forking-with-the-edit-button
 .. _`Pull Request`: https://help.github.com/articles/creating-a-pull-request
 .. _`running the tests`: http://python-eve.org/testing#running-the-tests
+.. _Redis: https://redis.io
 
 
diff --git a/dev-requirements.txt b/dev-requirements.txt
diff --git a/docs/index.rst b/docs/index.rst
@@ -98,7 +98,6 @@ link <http://eve.readthedocs.org/en/stable/>`_.
     snippets/index
     extensions
     contributing
-    testing
     support
     updates
     authors