From 056872ece4287434217c0c321f624d0d0ed3c74c Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 29 Sep 2023 10:06:08 +0000 Subject: [PATCH] markdown source builds Auto-generated via {sandpaper} Source : c1c43cb72e64a7c4f3748d8513e194cc2abe2094 Branch : main Author : Toby Hodges Time : 2023-09-29 10:04:49 +0000 Message : Merge pull request #286 from carpentries/89-workbench-troubleshooting-advice Add some website build troubleshooting tips --- infrastructure.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ md5sum.txt | 2 +- 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/infrastructure.md b/infrastructure.md index 5d2439f8a..535f22b77 100644 --- a/infrastructure.md +++ b/infrastructure.md @@ -499,6 +499,52 @@ Using this approach, we can build up our lesson one episode at a time. We have now learned everything we need to be able to use The Carpentries Workbench, and our focus can return to the process of developing a new lesson. +:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: spoiler + +## Troubleshooting the Lesson Build Process + +Sometimes, formatting errors and typos in the files of your repository can +cause the process that builds your lesson website to fail. + +You will likely first notice the failure to build the lesson if the lesson website is not showing the changes you made. +You may also receive an email from GitHub about the build failure if that is your preferred way of receiving notifications +(but it may take you some time to realise this). +The good thing is that GitHub keeps your previous lesson version online +until the error is fixed and a new build is completed successfully. +If you are not yet familiar with the GitHub interface, +it can be difficult to pinpoint the problem. + +Here are some points of advice that you can follow to help +find and fix the problem when you notice the build process fail. + +- When you first notice that there is a problem, **stop** editing your lesson: + any subsequent changes that you make will not be included in your lesson site until + the problem is fixed, and might introduce additional issues, + making it more difficult to find the original cause. +- **Look at the history** of commits + (the link with a reversing stopwatch icon and "NN commits" + at the top of the listing of files and folders in the repository homepage). + Is there a place where the build has a red cross instead of green circle? + If so, click on that commit to look at the "diff" + (where it shows which lines have been modified). + The error is likely to have been introduced by these changes. +- **Ask for help**: you can open an issue on your repository and tag a member of + The Carpentries team to ask for help finding the problem. + Alternatively, you can also ask for help in The Carpentries + Slack workspace. + (More about communication channels for discussing lesson development coming later in this training.) +- Waiting for the GitHub Actions process that builds the website to run can be tedious, + and slow down the process of troubleshooting: + it can take a few minutes for the process to reach the point where it encounters the problem. + It can be helpful to download the files for your lesson + and try to **build a version of the website on your local computer**, + where the build process will be much faster. + The Workbench documentation provides + [instructions for installing the infrastructure](https://carpentries.github.io/sandpaper-docs/#installation) + and [building a local preview of the lesson website](https://carpentries.github.io/sandpaper-docs/introduction.html#preview). + +:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: + ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: instructor ## Troubleshoot Lesson Builds (~10 mins) diff --git a/md5sum.txt b/md5sum.txt index cab755082..6ad0c8f89 100644 --- a/md5sum.txt +++ b/md5sum.txt @@ -13,7 +13,7 @@ "episodes/objectives.md" "79869207b33a74cf1887aff488b0b41c" "site/built/objectives.md" "2023-08-30" "episodes/episodes.md" "571f85f6160b89e7e571ba72a31db434" "site/built/episodes.md" "2023-08-25" "episodes/long-break1.md" "3a4802231bb8e44cc6c132d86afb7f78" "site/built/long-break1.md" "2023-08-21" -"episodes/infrastructure.md" "33b348ae8ae692db805eb4c2a16bb86d" "site/built/infrastructure.md" "2023-09-29" +"episodes/infrastructure.md" "d1652edb66dd21f3524ec8737b835ecd" "site/built/infrastructure.md" "2023-09-29" "episodes/short-break2.md" "05d1044278ce40ab59d9397db1f0e383" "site/built/short-break2.md" "2023-08-21" "episodes/episode-objectives.md" "b930e3b1659f6dd694c727e016efe925" "site/built/episode-objectives.md" "2023-08-25" "episodes/short-break3.md" "05d1044278ce40ab59d9397db1f0e383" "site/built/short-break3.md" "2023-08-21"