Github templates, contributing text (#115)

* Add templates for feature requests, bug reports, and new pull requests

* Describe how to contribute to the project

* Bump version, update readme

* Minor phrasing changes

* Mypy ignore pkg_resources import

* Update README badge link

.github/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing guidelines
+
+This page explains how you can contribute to the development of `alns` by submitting patches, extensions, or examples.
+
+The `alns` library is developed on [GitHub](https://github.com/N-Wouda/ALNS) using the [Git](https://git-scm.com/) version control system.
+
+## Where to go for discussions and help?
+
+Conversations about development and issues take place in the GitHub repository.
+Feel free to open a new issue if you have something to discuss.
+
+## Submitting a bug report
+
+- Include a short, self-contained code snippet that reproduces the problem
+- Specify the version information of the `alns` installation you use. 
+ You can do this by including the output of `import alns; alns.show_versions()` in your report.
+
+## Making changes to the code
+
+For a pull request to be accepted, you must meet the below requirements. 
+This greatly reduces the job of maintaining and releasing the software.
+
+- **One branch. One feature.** 
+ Branches are cheap and GitHub makes it easy to merge and delete branches with a few clicks. 
+ Avoid the temptation to lump in a bunch of unrelated changes when working on a feature, if possible. 
+ This helps us keep track of what has changed when preparing a release.
+- Commit messages should be clear and concise. 
+ This means a subject line of less than 80 characters, and, if necessary, a blank line followed by a commit message body.
+- Code submissions should always include tests.
+- Each function, class, method, and attribute needs to be documented using docstrings.
+ We conform to the [NumPy docstring standard](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
+- If you are adding new functionality, you need to add it to the documentation by editing (or creating) the appropriate file in `docs/source`.
+- Make sure your documentation changes parse correctly. Change into the top-level `docs/` directory and type:
+ ```shell
+ make clean
+ make html
+ ```
+ Check that the build output does not have *any* warnings due to your changes.

.github/ISSUE_TEMPLATE/BUG_REPORT.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Create a bug report highlighting an issue.
+title: ''
+labels: ''
+assignees: ''
+---
+
+#### Describe the bug
+
+[
+A clear and concise description of what the bug is. 
+This should explain **why** the current behaviour is a problem and why the expected output is a better solution.
+]
+
+#### Code sample
+
+```python
+# Your code here that produces the bug
+# This example should be self-contained, and so not rely on external data.
+# It should run in a fresh Python session, and so include all relevant imports.
+```
+
+<details>
+
+**Note**: Please be sure you are using the latest released version of `alns`, or a recent build of `master`.
+If your problem has been fixed in an unreleased version, you might be able to use `master` until a new release occurs.
+
+**Note**: If you are using a released version, have you verified that the bug exists in the master branch of this repository?
+
+</details>
+
+If the issue has not been resolved, please file it in the issue tracker.
+Make sure to include the version of Python you are using, and the version of `alns` you run.
+You can copy-paste the output of `import alns; alns.show_versions()` to achieve this.
+
+#### Expected Output
+
+A clear and concise description of what you expected to happen.
+

.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project.
+title: ''
+labels: ''
+assignees: ''
+---
+
+#### Is your feature request related to a problem? Please describe
+A clear and concise description of what the problem is. 
+For example, start with "I'm always frustrated when [...]", and go from there.
+
+#### Describe the solution you'd like
+A clear and concise description of what you want to happen.
+
+#### Describe alternatives you have considered
+A clear and concise description of any alternative solutions or features you have considered.
+
+#### Additional context
+Add any other context about the feature request here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+This PR:
+
+- [ ] Closes #xxxx.
+- [ ] Adds and passes relevant tests.
+- [ ] Has well-formatted code and documentation.
+
+<details>
+
+**Notes**:
+
+- It is essential that you add a test when making code changes.
+ This keeps the code coverage level up, and helps ensure the changes work as intended.
+- When fixing a bug, you must add a test that would produce the bug in the master branch, and then show that it is fixed with the new code. 
+- New code additions must be well formatted. Changes should pass the pre-commit workflow, which you can set up locally using [pre-commit](https://pre-commit.com/#intro). 
+- Docstring additions must render correctly, including escapes and LaTeX.
+
+</details>

README.md

@@ -1,5 +1,5 @@
 [![PyPI version](https://badge.fury.io/py/alns.svg)](https://badge.fury.io/py/alns)
-[![ALNS](https://github.com/N-Wouda/ALNS/actions/workflows/alns.yml/badge.svg)](https://github.com/N-Wouda/ALNS/actions/workflows/alns.yml)
+[![ALNS](https://github.com/N-Wouda/ALNS/actions/workflows/alns.yaml/badge.svg)](https://github.com/N-Wouda/ALNS/actions/workflows/alns.yaml)
 [![Documentation Status](https://readthedocs.org/projects/alns/badge/?version=latest)](https://alns.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/N-Wouda/ALNS/branch/master/graph/badge.svg)](https://codecov.io/gh/N-Wouda/ALNS)
 
@@ -36,10 +36,10 @@ showing how the ALNS library may be used. These include:
  demonstrate how one could tune ALNS parameters.
 
 Finally, the features notebook gives an overview of various options available 
-in the `alns` package (explained below). In the notebook we use these different
-options to solve a toy 0/1-knapsack problem. The notebook is a good starting
-point for when you want to use different schemes, acceptance or stopping criteria 
-yourself. It is available [here][5].
+in the `alns` package. In the notebook we use these different options to solve
+a toy 0/1-knapsack problem. The notebook is a good starting point for when you
+want to use different schemes, acceptance or stopping criteria yourself. It is
+available [here][5].
 
 ## How to use
 Our [documentation][7] provides a complete overview of the `alns` package. In 

alns/__init__.py

@@ -1,2 +1,3 @@
 from .ALNS import ALNS
 from .State import State
+from .show_versions import show_versions

alns/show_versions.py

@@ -0,0 +1,22 @@
+import sys
+
+# TODO switch over to importlib.metadata once we drop support for Python 3.7
+import pkg_resources # type: ignore
+
+
+def show_versions():
+ """
+ This function prints helpful debugging information that's useful when
+ filing bug reports.
+ """
+ alns = pkg_resources.get_distribution("alns")
+ numpy = pkg_resources.get_distribution("numpy")
+ matplotlib = pkg_resources.get_distribution("matplotlib")
+ python_version = ".".join(map(str, sys.version_info[:3]))
+
+ print("INSTALLED VERSIONS")
+ print("------------------")
+ print(f" alns: {alns.version}")
+ print(f" numpy: {numpy.version}")
+ print(f"matplotlib: {matplotlib.version}")
+ print(f" Python: {python_version}")

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "alns"
-version = "5.0.0"
+version = "5.0.1"
 description = "A flexible implementation of the adaptive large neighbourhood search (ALNS) algorithm."
 authors = ["Niels Wouda <n.wouda@apium.nl>"]
 license = "MIT"
@@ -55,6 +55,7 @@ addopts = "--cov=. --cov-report=xml"
 
 [tool.coverage.run]
 omit = [
+ "alns/show_versions.py", # only prints debug information
  "*/tests/*",
  "venv/*",
  "docs/*",