Initial restructuring of episodes post pilot 1

config.yaml

@@ -64,16 +64,19 @@ episodes:
 - 02-fair-research-software.md
 - 03-tools.md
 - 04-version-control.md
-- 05-code-readability.md
-- 06-code-testing.md
-- 07-documenting-code.md
-- 08-open-collaboration.md
-- 09-code-ethics.md
-- 10-wrap-up.md
+- 05-code-environment.md
+- 06-code-readability.md
+- 07-code-structure.md
+- 08-code-correctness.md
+- 09-code-documentation.md
+- 10-open-collaboration.md
+- 11-wrap-up.md
 
 # Information for Learners
-learners: 
+learners:
+- ci-for-testing.md
 - licensing.md
+- ethical-environmental-considerations.md
 
 # Information for Instructors
 instructors: 

episodes/03-tools.md

@@ -1,5 +1,5 @@
 ---
-title: "Tools and practices for research software development"
+title: "Tools and practices for FAIR research software development"
 teaching: 60
 exercises: 30
 ---
@@ -27,23 +27,7 @@ Here we will give an overview of the tools, how they help you achieve the aims o
 they work together. 
 In later episodes we will describe some of these tools in more detail.
 
-The table below summarises some tools and practices that can help with each of the FAIR software principles.
-
-| Tools and practices                                                                              | Findable | Accessible | Interoperable | Reusable |
-|--------------------------------------------------------------------------------------------------|----------|------------|---------------|----------|
-| Integrated development environments (e.g. VS Code) - development environments (run, test, debug) |          |            |               | x        |
-| Command line terminal (e.g. Bash)- reproducible workflows/pipelines                              |          |            | x             | x        |
-| Version control tools                                                                            | x        |            |               |          |
-| Testing                                                                                          |          | x          |               | x        |
-| Coding conventions and documentation                                                             |          | x          | x             | x        |
-| License                                                                                          |          | x          |               | x        |
-| Citation                                                                                         | x        |            |               | x        |
-| Software repositories (e.g. GitHub)                                                              | x        | x          |               |          |
-
-
-## Writing your code
-
-### Development environment
+## Development environment
 
 One of the first choices we make when writing code is what tool to use to do the writing.
 You can use a simple text editor such as Notepad, a terminal based editor with syntax highlighting such as Vim or Emacs, 
@@ -78,7 +62,7 @@ It is a single tool in which we can:
 
 Use VS Code to open the Python script and the data file from our project.
 
-### Command line tool/shell
+## Command line tool/shell
 
 In VS Code and similar IDEs you can often run the code by clicking a button or pressing some keyboard shortcut.
 If you gave your code to a colleague or collaborator they might use the same IDE or something different, 
@@ -103,7 +87,7 @@ without editing your code.
 With a command line interface, your code can be built into automated workflows so that the whole process from data 
 gathering to analysis to saving publication-quality results can be written in one Bash script and saved and reused.
 
-### Version control
+## Version control
 
 Version control means knowing what changes were made to your code and when. Many people who have worked on large 
 documents such as essays start doing this by saving files called `essay_draft`, `essay_version1.doc`, 
@@ -121,7 +105,10 @@ check if it is a change in the code due to using a newer version, or a change in
 We will be using the Git version control system, which can be used through the command line terminal, 
 in a browser or in a desktop application.
 
-### Testing
+## Code structure and style guidelines
+TODO
+
+## Code correctness
 
 Testing ensures that your code is correct and does what it is set out to do. When you write code you often feel very 
 confident that it is perfect, but when writing bigger codes or code that is meant to do complex operations it is 
@@ -132,15 +119,15 @@ be assured that it does work correctly on their machine.
 We will show different ways to test your code for different purposes. You need to think about what it is that is 
 important to you and any future users or collaborators to decide what kind of testing is most useful for you.
 
-### Documentation
+## Documentation
 
 Documentation comes in many forms - from the names of variables and functions in your code, additional comments 
 that explain some lines, up to a whole website full of documentation with function definitions, usage examples, 
 tutorials and guides. 
 You many not need as much documentation as a large commercial software product, but making your code Reusable relies 
 on other people being able to understand what your code does and how to use it.
 
-### Licences and citation
+## Licences and citation
 
 A licence states what people can legally do with your code, and what restrictions you have placed on it. 
 Whenever you want to use someone else's code you should check what license they have and make sure your use is legal. 
@@ -156,7 +143,7 @@ Both licensing law and citation procedures can vary depending on your country an
 so remember to check with a local team where you are. 
 Your local research IT support or library teams would be a good place to start.
 
-### Code repositories and registries
+## Code repositories and registries
 
 Having somewhere to share your code is fundamental to making it Findable. 
 Your institution might have a code repository, your research field may have a practice of sharing code via a specific 
@@ -167,32 +154,26 @@ depend on or reuse.
 
 We will discuss later how to share your code on GitHub and make it easy for others to find and use.
 
-## Summary
+## Summary of tools & practices
 
-### Findable
-
-- Describe your software - README
-- Software repository/registry - GitHub, registries
-- Unique persistent identifier - GitHub commits/tags/releases, Zenodo
-
-### Accessible
-
-- Software repository/registry
-- License
-- Language and dependencies
-
-### Interoperable
-
-- Explain functionality - readme, inline comments and documentation
-- Standard formats
-- Communication protocols - CLI/API
+The table below summarises some tools and practices that can help with each of the FAIR software principles.
 
-### Reusable
+| Tools and practices                                                                               | Findable | Accessible | Interoperable | Reusable |
+|---------------------------------------------------------------------------------------------------|----------|------------|---------------|----------|
+| Virtual development environments, programming language and dependencies - run, test, debug, share |          | x          |               | x        |
+| Integrated development environments/IDEs (e.g. VS Code, PyCharm) - run, test, debug               |          |            |               | x        |
+| Command line terminal (e.g. Bash, GitBash) - reproducible workflows/pipelines                     |          |            | x             | x        |
+| Version control tools                                                                             | x        |            |               |          |
+| Testing - code correctness and reproducibility                                                    |          | x          |               | x        |
+| Coding conventions and documentation                                                              |          | x          | x             | x        |
+| Explaining functionality/installation/running - README, inline comments and documentation         |          | x          | x             | x        |
+| Standard formats - e.g. for data exchange (CSV, YAML)                                             |          | x          | x             | x        |
+| Communication protocols - Command Line Interface (CLI) or Application Programming Interface (API) |          | x          | x             | x        |
+| License                                                                                           |          | x          |               | x        |
+| Citation                                                                                          | x        |            |               | x        |
+| Software repositories (e.g. GitHub, PyPi) or registries (e.g. BioTools)                           | x        | x          |               |          |
+| Unique persistent identifier (e.g. DOIs, commits/tags/releases) - Zenodo, FigShare GitHub         | x        | x          |               |          |
 
-- Document functionality/installation/running
-- Follow best practices where appropriate
-- License
-- Citation
 
 ## Checking your setup
 

episodes/04-version-control.md

@@ -26,15 +26,15 @@
 We will create a new software project from our existing code, make some changes to it and track them with
 version control, and then push those changes to a remote server for safe-keeping.
 
-### What is a version control system?
+## What is a version control system?
 
 Version control is the practice of tracking and managing changes to files.
 Version control systems are software tools that assist in the management of these
 file changes over time. They keep track of every modification to the files in a
 special database that allows users to "travel through time" and compare earlier
 versions of the files with the current state.
 
-### Motivation for using a version control system
+## Why use a version control system?
 
 The main motivation as scientists to use version control in our projects is for
 reproducibility purposes. As hinted to above, by tracking and storing every change
@@ -51,7 +51,7 @@
 allows many people to collaborate on the same project without a lot of manual
 effort to combine different items of work.
 
-### Git version control system 
+## Git version control system 
 
 Git is one of the version control systems around and the one we will be using in this course. 
 It is primarily used for source code management in software development but it can be used to track changes in files 
@@ -92,7 +92,6 @@
 Initially, we will use Git to start tracking changes to files on our local machines; later on we will start sharing our
 work on GitHub allowing other people to see and contribute to our work.
 
-
 ### Create a new repository
 
 Create a new directory in the `Desktop` folder for our work, and then change the current working directory 
@@ -309,8 +308,6 @@
  rename my code v2.py => my_code_v2.py (100%)
 ```
 
-
-
 ### Advanced solution
 
 We initially renamed the Python file using the `mv` command, and we than had to `git add` *both* `my_code_v2.py` 
@@ -464,11 +461,11 @@
 How many changes have they tried to make in each commit? 
 Discuss in pairs or small groups.
 
 1. ![Example Diff 1](fig/ex-diff-1.png)
 2. ![Example Diff 2](fig/ex-diff-2.png)
 
 
 To find out more about how to generate `diffs`, you can read the [Git documentation](git-diff-docs) or the [Tracking Changes episode][swc-git-lesson-track]
 from the [Software Carpentry Version control with Git lesson][swc-git-lesson].
 
 :::  solution
@@ -533,7 +530,7 @@
 
 Using `git reset` command produces a "cleaner" history, but does not tell the full story and your work.
 
-### Pushing to a Git server
+## Interacting with a remote Git server
 
 Git is also a distributed version control system, allowing us to synchronise work between any two or more copies of 
 the same repository - the ones that are not located on your machine.
@@ -548,32 +545,34 @@
 
 ![Git - distributed version control system, image from W3Docs (freely available)](episodes/fig/git-distributed.png){alt='2 Git repositories belonging to 2 different developers linked to a central repository and one another showing two way flow of information in each link'}
 
+[GitHub][github] is an online software development platform that can act as a central remote server.
+It uses Git underneath and provides facilities for storing, tracking, and collaborating on software projects.
+Other Git hosting services are available, such as [GitLab](https://gitlab.com) and [Bitbucket](https://bitbucket.org).
+
 Distributing our projects in this way also opens us up to collaboration,
 since colleagues would be able to access our projects, make their own copies on
 their machines, and conduct their own work.
 
-We will now go through how to push a local project to [GitHub](https://github.com),
-though other Git hosting services are available, such as [GitLab](https://gitlab.com)
-and [Bitbucket](https://bitbucket.org).
+We will now go through how to push a local project on [GitHub](https://github.com) and share it publicly.
 
 1. In your browser, navigate to <https://github.com> and sign into your account
 2. In the top right hand corner of the screen, there is a menu labelled "+" with
    a dropdown. Click the dropdown and select "New repository" from the options.
 
    ![*Creating a new GitHub repository*](fig/ep03_fig01-create_new_repo.jpg){ alt-text="Selecting the 'New repository' option from GitHub's dropdown menu" .image-with-shadow }
 
 3. You will be presented with some options to fill in or select while creating
    your repository. In the "Repository Name" field, type "spacewalks". This is
    the name of your project and matches the name of your local folder.
 
    ![*Naming the GitHub repository*](fig/ep03_fig02-repository_name.png){ alt-text="Setting the name of the repository on GitHub" .image-with-shadow }
 
    Ensure the visibility of the repository is "Public" and leave all other options
    blank. Since this repository will be connected to a local repository, it needs
    to be empty which is why we don't initialise with a README or add a license or
    `.gitignore` file. Click "Create repository" at the bottom of the page.
 
    ![*Complete GitHub repository creation*](fig/ep03_fig03-create_repository.jpg){ alt-text="Completing the creation of the GitHub repository" .image-with-shadow }
 
 4. Now you have created your repository, you need to send the files and the history
    you have stored on your local computer to GitHub's servers. GitHub provides
@@ -591,7 +590,7 @@
    squares to the right-hand side of the commands. Paste them into your terminal
    and run them.
 
    ![*Copy the commands to sync the local and remote repositories*](fig/ep03_fig04-copy_commands.jpg){ alt-text="Copying the commands to sync the local and remote repositories" .image-with-shadow }
 
 5. If you refresh your browser window, you should now see the two files `my-code-v2.py`
    and `data.json` visible in