Add issues templates

.github/workflows/update-issue.yaml

@@ -0,0 +1,23 @@
+name: Create new issues from markdown files (.issues/) when this repo is used as a template for a new one
+
+on:
+  release:
+  types: [published]
+
+jobs:
+  create_issues:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    - name: Create issues from markdown files
+      run: |
+        for file in .issues/*.md; do
+          title=$(head -n 1 $file)
+          body=$(tail -n +2 $file)
+          echo "Creating issue with title: $title"
+          echo "$body" | gh issue create --title "$title" --body "$body"
+        done
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.issues/exercise_1.md

@@ -0,0 +1,30 @@
+# Exercise 1
+This exercise will look at understanding what a given python function (`times.py`) does, and writing a test to check that it works as expected.
+
+1. Fork this repository repository and clone it on your computer.
+2. Make sure you have read the note chapters on [Testing basics](https://github-pages.ucl.ac.uk/rsd-engineeringcourse/ch03tests/01testingbasics.html), [The Fields of Saskatchewan](https://github-pages.ucl.ac.uk/rsd-engineeringcourse/ch03tests/02SaskatchewanFields.html) and [Test frameworks](https://github-pages.ucl.ac.uk/rsd-engineeringcourse/ch03tests/03pytest.html).
+3. Start by reading the code in `times.py`, understanding what it does, and running it (before making any modifications to it).
+	i. Have you seen [`datetime`](https://docs.python.org/3.7/library/datetime.html) before?
+   ii. Play using your favourite tool (notebook, terminal, scripts) with the functions and objects used in `times.py`.
+5. The next step consists of converting the __main__ part of the code into a unit test.
+    i. Create a new file called `test_times.py` in the same directory where `times.py` is.
+   ii. Make the `overlap_time` function accessible to that file. (*Hint*: You need to `import` the file).
+  iii. Move the content from the `if __name__ ...` block from `times.py` to a function called `test_given_input` into `test_times.py` and fill the gaps for `result` and `expected`. (For now, you can copy the output of the program as the expected value)
+```python
+def test_given_input():
+    ...
+    result = ...
+    expected = ...
+    assert result == expected
+```
+7. Run `pytest` on that directory and see whether the test is picked up by `pytest` and whether it passes. If the test doesn't pass, see if you can find what is going wrong.
+8. When you are happy with your solution (or want some feedback!):
+	  i. Push your new code to your own fork.
+     ii. On GitHub, open a pull request from your fork to the original repository.
+    iii. In the description, include the text `Answers neuroinformatics-unit/rse-best-practices-playground#1`. This will list your PR to this issue.
+    iv. On the PR text, comment on what you found difficult or interesting, or something you learned.
+9. Choose one of the other pull requests listed on this issue, and leave a review. Comment on things you find interesting or don't understand, any problems you think you spot, good solutions, or potential improvements.
+10. Mark the assignment on Moodle as complete.
+11. Think about what other aspects of `times.py` should be tested and report them on the Moodle questionnaire.
+
+If you have questions or get stuck, ask on Moodle or book an office hours slot!

.issues/exercise_2.md

@@ -0,0 +1,34 @@
+# Exercise 2
+This exercise will show why it is important to keep documentation accurate, and how to do this automatically using docstrings and doctests.
+
+## Setup
+Make sure you've had a look at the course notes on [documentation](http://github-pages.ucl.ac.uk/rsd-engineeringcourse/ch04packaging/04documentation.html) so that you understand some of the background around docstrings and doctests. There you can also find how to use Sphinx to generate your website containing the docstrings of your methods. If you want more information you can find it in the [Sphinx docs](https://www.sphinx-doc.org/en/master/usage/quickstart.html).
+We suggest using [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html), i.e. the Numpy style guide for docstrings.
+
+## Exercises
+### Write docstrings
+The methods in `times.py` don't have a complete docstring. Based on your understanding of the methods, write a docstring using Numpy formatting. Describe what the method does, what are the inputs and the outputs.
+You can change the examples later.
+
+### Run doctests
+Use the `doctest` module to see whether the documentation of the code is accurate: `python -m doctest times.py`.
+Try to understand the structure of the output - what errors are reported, are they what you expected from looking at the code in the previous steps?
+
+### Correct the examples in the docstrings
+If there are errors, try to figure out where the mismatch between the documentation (intended behaviour) and the actual behaviour of the function exists.
+Correct usage examples in the `times.py` function that are incorrect.
+Do your example cover all the functionality described in the docstring?
+Run again `python -m doctest times.py` to evaluate your new examples.
+
+## Make your docs website
+Thanks to the NIU `cookiecutter`, this repo contains the `docs/` folder the resources required to build a website using Sphinx.
+Install the dev dependencies of the package to be able to run `sphinx-build`.
+Update the `api_index.rst` file to include the methods in `times.py`.
+Build the website using `sphinx-build docs/source docs/build`. The build folder contains the generated artefacts necessary for the website. By opening `index.html` you can navigate the website.
+Does the website look as you expected?
+Remember to delete the previous build folder before running again `shphinx-build`.
+
+## Submit a Pull Request
+Once you have completed or made progress on the exercises, open a pull request and ask for a review.
+
+Create a pull request (PR) from your branch to the upstream repository. Add a meaningful title to that PR and a link to this issue: `Answers neuroinformatics-unit/rse-best-practices-playground#2`.

.issues/exercise_3.md

@@ -0,0 +1,21 @@
+# Exercise 3
+For this exercise, we will look at how to rewrite (refactor) existing code in different ways, and what benefits each new structure offers.
+
+## Some reading
+How to write better code? People have interrogated themselves on this question a lot and they came up with a set of useful principles to guide their craft.
+One of them is [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), another one is the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) (part of [SOLID](https://en.wikipedia.org/wiki/SOLID)).
+Another good read at this stage is [PEP 8](https://peps.python.org/pep-0008/), the style guide for python code.
+
+## Let's refactor!
+According to what you have been reading, do you see ways to improve the methods in `times.py`?
+
+## Review your changes
+Run your script. Does it still behave as expected?
+Do your tests still pass? Do they still map to the new methods you have created?
+Are your docstrings still reflecting the behaviour of your methods?
+
+## Final tasks
+Commit your changes!
+Create a pull request from your branch to the original friend-group repository and use the text in the description to link your PR to this issue `Answers neuroinformatics-unitrse-best-practices-playground#3`.
+Think of the benefits and drawbacks of this approach compared to the original version.
+If you have time, think of other changes you consider useful and try them.

MANIFEST.in

@@ -1,6 +1,7 @@
 include LICENSE
 include README.md
 
+recursive-include .issues *.md
 recursive-include rse_best_practices_playground *.py
 recursive-include tests *.py