Instructor Notes

This is a placeholder file. Please add content here.

Course introduction

---

Better start with a software project

---

Choose how you teach version control steps from here

At this point in the lesson, you may choose to demonstrate how the same steps of staging and committing changes can also be achieved with the VS Code graphical interface.

The Source Control interface to Git in VS Code

Depending on your relative levels of comfort working with that graphical interface and the command line interface to Git, you can choose how you want to demonstrate the remaining steps in this episode and when we use Git again elsewhere. The lesson will continue to present version control steps with the command line interface only.

---

Reproducible software environments

---

Instructor Note

Some learners may encounter issues when installing packages or trying to restore recorded environments. To assist with troubleshooting during workshops, we have compiled a list of common issues that instructors have observed in the past.

If you run into problems not mentioned here, please open an issue in the lesson repository so we can track them and update the lesson material accordingly.

Troubleshooting package installation issues

• Try using install.packages('some.pkg', dependencies = TRUE)

• Use .libPaths() and verify that it includes at least one folder for which the user has write permisisons. If that’s not the case, try setting R_LIBS_USER="some/writable/path" via either Sys.setenv() or through an .Renviron file.

• {pak} often does a better job of figuring out and installing (system) dependencies:

  R

  install.packages('pak')
  pak::pkg_deps_tree('some.pkg')
  pak::pkg_sysreqs('some.pkg')

  You can tell {renv} to use {pak} by default by setting RENV_CONFIG_PAK_ENABLED=TRUE

General recommendations on using {renv}

• Often it’s easier to start with a fresh environment rather than trying to fix an existing one. You can do this by deleting the renv folder and renv.lock file, then calling renv::init() again.

---

Code readability

---

Instructor Note

You will need to share the code below with the learners via copy-and-paste either in shared notes or chat in a virtual training. Then you can highlight and describe the changes.

---

Code structure

---

Instructor Note

You will need to share the code below with the learners via copy-and-paste either in shared notes or chat in a virtual training. Then you can highlight and describe the changes.

---

Instructor Note

You will need to share the code below with the learners via copy-and-paste either in shared notes or chat in a virtual training. Then you can highlight and describe the changes.

---

Instructor Note

You will need to share the code below with the learners via copy-and-paste either in shared notes or chat in a virtual training. Then you can highlight and describe the changes.

---

Code correctness & testing

---

Software documentation

---

Instructor Note

You may want to share the following README excerpts directly in chat or the shared notes document with learners to copy-paste.

---

Instructor Note

Make sure to mention the extra content on different open source software licences, briefly cover it if there is time. Then focus on the technicalities of adding a license file to a code repository (as there is likely not going to be enough time to spend on different license types).

---

Software management & collaboration

---

Optional challenge: archive our GitHub repository to Zenodo (5 min)

You can choose to do the following as an exercise or by live coding based on what you think the learners would prefer. You can copy the detailed instructions below to give them it as an exercise.

---

Optional challenge: add a DOI and software version to the citation file (5 min)

You can choose to do the following as an exercise or by live coding based on what you think the learners would prefer. You can copy the the detailed instructions below to give it as an exercise.

---

Wrap-up

---