Merge pull request #33 from UCL-ARC/32-add-refactoring-lesson

Add refactoring lesson

Author: connoraird

README.md

@@ -1,84 +1,20 @@
-# The Carpentries Workbench Template Markdown Lesson
+# Fortran unit testing lesson
 
-This lesson is a template lesson that uses [The Carpentries Workbench][workbench]. 
+A lesson for teaching how to unit test Fortran code.
 
-## Note about lesson life cycle stage
-Although the `config.yaml` states the life cycle stage as pre-alpha, **the template is stable and ready to use**. The life cycle stage is preset to `"pre-alpha"` as this setting is appropriate for new lessons initialised using the template.
+## Building the website locally
 
-## Create a new repository from this template
+From within RStudio run the following commands. First, install the needed dependencies.
 
-To use this template to start a new lesson repository, 
-make sure you're logged into Github.   
-Visit https://github.com/carpentries/workbench-template-md/generate
-and follow the instructions.
-Checking the 'Include all branches' option will save some time waiting for the first website build
-when your new repository is initialised.
+```r
+install.packages(c("sandpaper", "varnish", "pegboard")) # This may not need to be called as frequently as the following commands
+```
 
-If you have any questions, contact [@tobyhodges](https://github.com/tobyhodges)
+Then can build the site
 
-## Configure a new lesson
+```r
+setwd('/path/to/fortran-unit-testing-lesson')
+sandpaper::build_lesson()
+```
 
-Follow the steps below to
-complete the initial configuration of a new lesson repository built from this template:
-
-1. **Make sure GitHub Pages is activated:**
-   navigate to _Settings_,
-   select _Pages_ from the left sidebar,
-   and make sure that `gh-pages` is selected as the branch to build from.
-   If no `gh-pages` branch is available, check the _Actions_ tab to see if the first
-   website build workflows are still running.
-   If they're not running yet, you may need to manually enable them via the _Actions_ tab.
-   The branch should become available when those have completed.
-1. **Adjust the `config.yaml` file:**
-   this file contains global parameters for your lesson site.
-   Individual fields within the file are documented with comments (beginning with `#`)
-   At minimum, you should adjust all the fields marked 'FIXME':
-   - `title`
-   - `created`
-   - `keywords`
-   - `life_cycle` (the default, _pre-alpha_, is the appropriate for brand new lessons)
-   - `contact`
-1. **Annotate the repository** with site URL and topic tags:
-   navigate back to the repository landing page and
-   click on the gear wheel/cog icon (similar to ⚙️) 
-   at the top-right of the _About_ box.
-   Check the "Use your GitHub Pages website" option,
-   and [add some keywords and other annotations to describe your lesson](https://cdh.carpentries.org/the-carpentries-incubator.html#topic-tags)
-   in the _Topics_ field.
-   At minimum, these should include:
-   - `lesson`
-   - the life cycle of the lesson (e.g. `pre-alpha`)
-   - the human language the lesson is written in (e.g. `deutsch`)
-1. **Adjust the 
-   `CITATION.cff`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and `LICENSE.md` files**
-   as appropriate for your project.
-   -  `CITATION.cff`:
-      this file contains information that people can use to cite your lesson,
-      for example if they publish their own work based on it.
-      You should [update the CFF][cff-sandpaper-docs] now to include information about your lesson,
-      and remember to return to it periodically, keeping it updated as your
-      author list grows and other details become available or need to change.
-      The [Citation File Format home page][cff-home] gives more information about the format,
-      and the [`cffinit` webtool][cffinit] can be used to create new and update existing CFF files.
-   -  `CODE_OF_CONDUCT.md`: 
-      if you are using this template for a project outside The Carpentries,
-      you should adjust this file to describe 
-      who should be contacted with Code of Conduct reports,
-      and how those reports will be handled.
-   -  `CONTRIBUTING.md`:
-      depending on the current state and maturity of your project,
-      the contents of the template Contributing Guide may not be appropriate.
-      You should adjust the file to help guide contributors on how best
-      to get involved and make an impact on your lesson.
-   -  `LICENSE.md`:
-      in line with the terms of the CC-BY license,
-      you should ensure that the copyright information 
-      provided in the license file is accurate for your project.
-1. **Update this README with 
-   [relevant information about your lesson](https://carpentries.github.io/lesson-development-training/collaborating-newcomers.html#readme)**
-   and delete this section.
-
-[cff-home]: https://citation-file-format.github.io/
-[cff-sandpaper-docs]:  https://carpentries.github.io/sandpaper-docs/editing.html#making-your-lesson-citable
-[cffinit]: https://citation-file-format.github.io/cff-initializer-javascript/
-[workbench]: https://carpentries.github.io/sandpaper-docs/
+This will create a local build of the site at [site/docs/index.html](./site/docs/index.html).

config.yaml

@@ -34,7 +34,7 @@ life_cycle: 'pre-alpha'
 license: 'CC-BY 4.0'
 
 # Link to the source repository for this lesson
-source: 'https://github.com/UCL-ARC/fortran-unit-testing-lesson/'
+source: 'https://github.com/UCL-ARC/fortran-unit-testing-lesson'
 
 # Default branch of your lesson
 branch: 'main'
@@ -66,8 +66,8 @@ contact: 'c.aird@ucl.ac.uk'
 
 # Order of episodes in your lesson
 episodes: 
-- 1-intro-to-unit-tests.md
-- 2-intro-to-fortran-unit-tests.md
+- 1-what-is-a-unit-tests.md
+- 2-refactor-fortran.md
 - 3-fortran-unit-test-syntax.md
 - 4-debugging-a-broken-test.md
 - 5-testing-parallel-code.md

episodes/1-what-is-a-unit-tests.md

@@ -20,7 +20,6 @@ exercises:
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-## What is unit testing?
 
 Unit testing is a way of verifying the validity of a code base by testing its smallest individual components, or **units**.
 
@@ -35,14 +34,14 @@ Several key aspects define a unit test. They should be...
 
 ::::::::::::::::::::::::::::::::::::: callout
 
-#### Other forms of testing
+### Other forms of testing
 
 There are other forms of testing, such as integration testing in which two or more units of a code base are tested to verify that they work together, or that they are correctly **integrated**.
 However, today we are focusing on unit tests as it is often the case that many of these larger tests are written using the same test tools and frameworks, hence we will make progress with both by starting with unit testing.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-### What does a unit test look like?
+## What does a unit test look like?
 
 All unit tests tend to follow the same pattern of Given-When-Then.
 
@@ -58,7 +57,7 @@ All unit tests tend to follow the same pattern of Given-When-Then.
 
 ::::::::::::::::::::::::::::::::::::: challenge 
 
-#### Challenge 1: Write a unit test in sudo code.
+### Challenge 1: Write a unit test in sudo code.
 
 Assuming you have a function `reverse_array` which reverses the order of an allocated array. Write a unit test in pseudo code for `reverse_array` using the pattern above.
 
@@ -82,7 +81,7 @@ for each element in `input_array`:
 :::::::::::::::::::::::::::::::::
 ::::::::::::::::::::::::::::::::::::::::::
 
-### When should unit tests be run?
+## When should unit tests be run?
 
 A major benefit of unit tests is the ability to identify bugs at the earliest possible stage. Therefore, unit tests should be run frequently throughout the development process. Passing unit tests give you and your collaborators confidence that changes to your code aren't modifying the previously expected behaviour, so run your unit tests...
 
@@ -95,7 +94,7 @@ A major benefit of unit tests is the ability to identify bugs at the earliest po
 
 Basically, all the time.
 
-### Do we really need unit tests?
+## Do we really need unit tests?
 
 Yes! 
 
@@ -117,7 +116,7 @@ This is much clearer. We immediately have an idea of what could be going wrong a
 
 ::::::::::::::::::::::::::::::::::::: challenge 
 
-### Challenge 2: Unit test bad practices
+## Challenge 2: Unit test bad practices
 
 Take a look at [1-into-to-unit-tests/challenge](https://github.com/UCL-ARC/fortran-unit-testing-exercises/tree/main/episodes/1-into-to-unit-tests/challenge) in the exercises repository.