Misc/contributor flow (#111)

 * Update contributor guidelines as part of the package documentation.
 * Add GitHub templates for new issues (bug reports/feature requests).
 * Add GitHub pull request templates.
 * Update the CONTRIBUTING guidelines.
* Move flake8 config into setup.cfg and remove tox.ini.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report that describes an issue
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!-- Please replace the text in the individual sections below. -->
+
+### Description
+
+A concise description of what is causing an issue and what you expected to happen.
+
+### To reproduce
+
+Please copy & paste the code that is triggering the issue into this section and describe the context and prior steps that lead to the problem with as much detail as possible.
+
+### Error output
+
+If possible, copy any terminal outputs or attach screenshots that provide additional information on the problem.
+
+### System configuration
+
+Please complete the following information:
+
+ - Operating System [e.g. macOS]:
+ - Version of Python [e.g. 3.7]:
+ - Version of signac [e.g. 1.0]:
+
+Or copy & paste the output of: `python -c 'import platform; print(platform.platform()); import sys; print(sys.version); import signac; print(signac.__version__)'`

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest a new feature for signac
+title: ''
+labels: ''
+assignees: ''
+
+---
+<!-- Please replace the text in the individual sections below. -->
+
+### Feature description
+
+A concise description of the enhancement that this feature provides or the problem it solves.
+For example: "I would like to ..." or "It would be nice if it was easier to ...".
+
+### Proposed solution
+
+A description of how you would like a possible solution to look like.
+
+*Proposals for an implementation of the idea are welcome, but not necessary.*
+
+### Additional context
+
+Any alternative solutions you might have considered or other information that might be helpful to understand this feature request.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,35 @@
+<!-- Provide a general summary of your changes in the Title above -->
+
+## Description
+<!-- Describe your changes in detail -->
+
+## Motivation and Context
+<!-- Why is this change required? What problem does it solve? -->
+<!-- If it fixes an open issue, please link to the issue here. -->
+
+## Types of Changes
+<!-- Please select all items that apply either now or after creating the pull request: -->
+- [ ] Documentation update
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change<sup>1</sup>
+
+This pull request is based on
+- [ ] *master*, because it is a bug fix or an update to the documentation.
+- [ ] *develop*, because it introduces a new feature.
+
+<sup>1</sup>The change breaks (or has the potential to break) existing functionality.
+
+## Checklist:
+<!-- Please select all items that apply either now or after creating the pull request. -->
+<!-- If you are unsure about any of these items, do not hesitate to ask! -->
+- [ ] I am familiar with the [**Contributing Guidelines**](https://github.com/glotzerlab/signac/blob/master/CONTRIBUTING.md).
+- [ ] I agree with the terms of the [**Contributor Agreement**](https://github.com/glotzerlab/signac/blob/master/ContributorAgreement.md).
+- [ ] My name is on the [list of contributors](https://github.com/glotzerlab/signac/blob/master/contributors.txt).
+- [ ] My code follows the [code style guideline](https://github.com/glotzerlab/signac/blob/misc/contributor-flow/CONTRIBUTING.md#code-style) of this project.
+- [ ] The changes introduced by this pull request are covered by existing or newly introduced tests.
+
+If necessary:
+- [ ] I have updated the API documentation as part of the package doc-strings.
+- [ ] I have created a separate pull request to update the [framework documentation](https://docs.signac.io/) on [signac-docs](https://github.com/glotzerlab/signac-docs) and linked it here.
+- [ ] I have updated the [changelog](https://github.com/glotzerlab/signac/blob/master/changelog.txt).

CONTRIBUTING.md

@@ -2,20 +2,31 @@
 
 ## Feedback
 
-The report of issues and the proposal of new features is very welcome.
-Please use the [issue page](https://github.com/glotzerlab/signac/issues) for this.
+Issue reports and feature proposals are very welcome.
+Please use the [GitHub issue page](https://github.com/glotzerlab/signac/issues/) for this.
 
 ## Contributing code
 
 Code contributions to the signac open-source project are welcomed via pull requests on GitHub.
 Prior any work you should contact the signac developers to ensure that the planned development meshes well with the directions and standards of the project.
 All contributors must agree to the Contributor Agreement ([ContributorAgreement.md](ContributorAgreement.md)) before their pull request can be merged.
 
-General guidelines:
+### General guidelines
 
-  * The signac development is based on the [git flow model][gitflow], which means new features should be developed within a feature branch based off the 'develop' branch.
-  * If external library depedencies cannot be avoided, they must be added as *soft depedencies*.
-  * All contributed code should pass `flake8` checks as specified in the tox.ini configuration file.
-  * All new features require unit tests.
+  * Use the [git flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) model of development:
+    - Bug fixes should be based on `master` if they affect a current release of the package.
+    - New features should be developed in a feature branch based on `develop`.
+  * Write code that is compatible with all supported versions of Python (listed in [setup.py](https://github.com/glotzerlab/signac/blob/master/setup.py)).
+  * Avoid introducing dependencies -- especially those that might be harder to install in high-performance computing environments.
+  * Create [unit tests](https://en.wikipedia.org/wiki/Unit_testing) and [integration tests](https://en.wikipedia.org/wiki/Integration_testing) that cover the common cases and the corner cases of the code.
+  * Preserve backwards-compatibility whenever possible, and make clear if something must change.
+  * Document any portions of the code that might be less clear to others, especially to new developers.
+  * Write API documentation in this package, and put usage information, guides, and concept overviews in the [framework documentation](https://docs.signac.io/) ([source](https://github.com/glotzerlab/signac-docs/)).
 
-[gitflow]: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
+Please see the [Support](https://docs.signac.io/projects/signac-core/en/latest/support.html) section as part of the documentation for detailed development guidelines.
+
+### Code Style
+
+Code submitted to the signac project must adhere to the [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/) with the exception that lines may have up to 100 characters.
+
+We recommend to use [flake8](http://flake8.pycqa.org/en/latest/) and [autopep8](https://pypi.org/project/autopep8/) to find and fix any code style issues prior to committing and pushing.

doc/support.rst

@@ -1,10 +1,137 @@
 .. _support:
 
+=======================
 Support and Development
------------------------
+=======================
 
 To get help using the **signac** package, either send an email to `signac-support@umich.edu <mailto:signac-support@umich.edu>`_ or join the `signac gitter chatroom <https://gitter.im/signac/Lobby>`_.
 
 The **signac** package is hosted on `GitHub <https://github.com/glotzerlab/signac.git>`_ and licensed under the open-source BSD 3-Clause license.
 Please use the `repository's issue tracker <https://github.com/glotzerlab/signac/issues>`_ to report bugs or request new features.
 
+
+Code contributions
+==================
+
+This project is open-source.
+Users are highly encouraged to contribute directly by implementing new features and fixing issues.
+Development for packages as part of the **signac** framework should follow the general development guidelines outlined `here <http://docs.signac.io/en/latest/community.html#contributions>`_.
+
+A brief summary of contributing guidelines are outlined in the `CONTRIBUTING.md <https://github.com/glotzerlab/signac/blob/master/CONTRIBUTING.md>`_ file as part of the repository.
+All contributors must agree to the `Contributor Agreement <https://github.com/glotzerlab/signac/blob/master/ContributorAgreement.md>`_ before their pull request can be merged.
+
+Set up a development environment
+--------------------------------
+
+Start by `forking <https://github.com/glotzerlab/signac/fork/>`_ the project.
+
+We highly recommend to setup a dedicated development environment,
+for example with `venv <https://docs.python.org/3/library/venv.html>`_:
+
+.. code-block:: bash
+
+    ~ $ python -m venv ~/envs/signac-dev
+    ~ $ source ~/envs/signac-dev/bin/activate
+    (signac-dev) ~ $ pip install six flake8
+
+or alternatively with `conda <https://conda.io/docs/>`_:
+
+.. code-block:: bash
+
+    ~ $ conda create -n signac-dev python=3 six flake8
+    ~ $ activate signac-dev
+
+Then clone your fork and install the package from source with:
+
+.. code-block:: bash
+
+    (signac-dev) ~ $ cd path/to/my/fork/of/signac
+    (signac-dev) signac $ pip install -e . -r requirements-dev.txt
+
+The ``-e`` option stands for *editable*, which means that the package is directly loaded from the source code repository.
+That means any changes made to the source code are immediately reflected upon reloading the Python interpreter.
+
+Finally, we recommend to setup a `Flake8 <http://flake8.pycqa.org/en/latest/>`_ git commit hook with:
+
+.. code-block:: bash
+
+    (signac-dev) signac $ flake8 --install-hook git
+    (signac-dev) signac $ git config --bool flake8.strict true
+
+With the *flake8* hook, your code will be checked for syntax and style before you make a commit.
+The continuous integration pipeline for the package will perform these checks as well, so running these tests before committing / pushing will prevent the pipeline from failing due to style-related issues.
+
+The git-flow development workflow
+---------------------------------
+
+Prior to working on a patch, it is advisable to create an `issue <https://github.com/glotzerlab/signac/issues>`_ that describes the problem or proposed feature.
+This means that the code maintainers and other users get a chance to provide some input on the scope and possible limitations of the proposed changes, as well as advise on the actual implementation.
+
+All code changes should be developed within a dedicated git branch and must all be related to each other.
+Unrelated changes, such as minor fixes to unrelated bugs encountered during implementation, spelling errors, and similar typographical mistakes must be developed within a separate branch.
+
+Branches should be named after the following pattern: ``<prefix>/issue-<#>-optional-short-description``.
+Choose from one of the following prefixes depending on the type of change:
+
+  * ``fix/``: Any changes that fix a bug in the code or an error in the documentation; should be based on the *master* branch.
+  * ``feature/``: Any changes that introduce a new feature; should be based on the *develop* branch.
+  * ``release/``: Reserved for release branches.
+
+If your change does not seem to fall into any of the above mentioned categories, use ``misc/``.
+
+Once you are content with your changes, push the new branch to your forked repository and create a pull request into the main repository.
+Feel free to push a branch before completion to get input from the maintainers and other users, but make sure to add a comment that clarifies that the branch is not ready for merge yet.
+
+Testing
+-------
+
+Prior to fixing an issue, implement unit tests that *fail* for the described problem.
+New features must be tested with unit and integration tests.
+To run tests, execute:
+
+.. code-block:: bash
+
+    (signac-dev) signac $ python -m unittest discover tests/
+
+
+Building documentation
+----------------------
+
+Building documentation requires the `sphinx <http://www.sphinx-doc.org/en/master/>`_ package which you will need to install into your development environment.
+
+.. code-block:: bash
+
+   (signac-dev) signac $ pip install Sphinx sphinx_rtd_theme
+
+Then you can build the documentation from within the ``doc/`` directory as part of the source code repository:
+
+.. code-block:: bash
+
+    (signac-dev) signac $ cd doc/
+    (signac-dev) doc $ make html
+
+.. note::
+
+    Documentation as part of the package should be largely limited to the API.
+    More elaborate documentation on how to integrate **signac** into a computational workflow should be documented as part of the `framework documentation <https://docs.signac.io>`_, which is maintained `here <https://github.com/glotzerlab/signac-docs>`_.
+
+
+Updating the changelog
+----------------------
+
+To update the changelog, add a one-line description to the `changelog.txt <https://github.com/glotzerlab/signac/blob/master/changelog.txt>`_ file within the ``next`` section.
+For example:
+
+.. code-block:: bash
+
+    next
+    ----
+
+    - Fix issue with launching rockets to the moon.
+
+    [0.6.3] -- 2018-08-22
+    ---------------------
+
+    - Fix issue related to dynamic data spaces, ...
+
+Just add the ``next`` section in case it doesn't exist yet.

setup.cfg

@@ -3,3 +3,7 @@ description-file = README.md
 
 [bdist_wheel]
 universal=1
+
+[flake8]
+max-line-length=100
+exclude = configobj,passlib,tqdm,six.py,cite.py,conf.py