Merge pull request #62 from alan-turing-institute/main

[pull] main from alan-turing-institute:main

.all-contributorsrc

@@ -1,6 +1,8 @@
 {
+  "_comment": "This JSON file controls the behaviour of the all contributors bot. A description of the keys can be found here: https://allcontributors.org/docs/en/bot/configuration",
   "files": [
-    "README.md"
+    "README.md",
+    "book/website/afterword/contributors-record.md"
   ],
   "imageSize": 100,
   "contributorsPerLine": 7,
@@ -4295,6 +4297,24 @@
       "contributions": [
         "translation"
       ]
+    },
+    {
+      "login": "spier",
+      "name": "Sebastian Spier",
+      "avatar_url": "https://avatars.githubusercontent.com/u/163029?v=4",
+      "profile": "https://spier.hu",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "srtee",
+      "name": "Shern Tee",
+      "avatar_url": "https://avatars.githubusercontent.com/u/60586092?v=4",
+      "profile": "https://github.com/srtee",
+      "contributions": [
+        "content"
+      ]
     }
   ],
   "projectName": "the-turing-way",

.github/ISSUE_TEMPLATE/new_chapter.yml

@@ -54,14 +54,14 @@ body:
     label: Updates
     description: Please comment on this issue with updates so that all the important information is available at a glance. You may use the checklist here to get started or create a new checklist in the comments.
     options:
-      - label: Write chapter outline
-      - label: Add material to the chapter
-      - label: Combine materials into a readable chapter
-      - label: Proofread
-      - label: Create PR and link in the comments
-      - label: Request reviews
-      - label: Address reviews
-      - label: Merge to main branch
+    - label: Write chapter outline
+    - label: Add material to the chapter
+    - label: Combine materials into a readable chapter
+    - label: Proofread
+    - label: Create PR and link in the comments
+    - label: Request reviews
+    - label: Address reviews
+    - label: Merge to main branch
 - type: markdown
   attributes:
     value: "**When you are ready to create a pull request for your chapter please don't forget to add a link in the comments on this issue.**"

.github/workflows/ci.yml

@@ -21,9 +21,9 @@ defaults:
   run:
     shell: bash
 
-# run job
 jobs:
-  build-jb-and-check-links:
+  build-jb:
+    name: Build
     if: (github.event.pull_request) && !contains(github.head_ref, 'all-contributors')
     strategy:
       matrix:
@@ -52,10 +52,33 @@ jobs:
           cd ./book/website
           jupyter-book build . -W --keep-going
 
-      - name: Run html proofer
-        if: matrix.os == 'ubuntu-latest'
-        uses: chabad360/htmlproofer@master
+  offline-link-check:
+    name: Link Check
+    needs: build-jb
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout-repository
+        uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -r ./book/website/requirements.txt
+
+      - name: Build Jupyter-Book
+        run: |
+          cd ./book/website
+          jupyter-book build .
+
+      - name: Check offline links
+        uses: lycheeverse/[email protected]
         with:
-          directory: "./book/website/_build/html"
-          arguments: --assume-extension --disable-external --only_4xx
-        continue-on-error: true
+          args: --config './lychee.toml' --no-progress --offline 'book/website/_build/html/**/*.html' 'book/website/_build/html/**/*.md'
+          fail: true
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} # Use runners GitHub token to avoid rate limiting

.github/workflows/external_link_check.yml

@@ -0,0 +1,58 @@
+name: External Link Check
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * MON"
+
+jobs:
+  external-link-check:
+    name: External Link Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout-repository
+        uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -r ./book/website/requirements.txt
+
+      - name: Build Jupyter-Book
+        run: |
+          cd ./book/website
+          jupyter-book build .
+
+      - name: Restore lychee cache
+        uses: actions/cache@v3
+        with:
+          path: .lycheecache
+          key: cache-lychee-${{ github.sha }} # save cache using commit sha
+          restore-keys: cache-lychee- # restore latest cache (not a specific commit)
+
+      - name: Check links
+        uses: lycheeverse/[email protected]
+        with:
+          args: --config './lychee.toml' --no-progress 'book/website/_build/html/**/*.html'
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} # Use runners GitHub token to avoid rate limiting
+
+      - name: Concatenate Lychee output with issue heaser
+        run: |
+          cat .github/workflows/resources/external_link_check_header.md lychee/out.md > issue_text.md
+
+      - name: Update Issue
+        uses: peter-evans/create-issue-from-file@v4
+        with:
+          title: Broken links
+          issue-number: 3171
+          content-filepath: issue_text.md
+          token: ${{secrets.GITHUB_TOKEN}}
+          labels: |
+            infrastructure
+            caretaking

.github/workflows/resources/external_link_check_header.md

@@ -0,0 +1,44 @@
+# Broken Links
+
+**This is an automated issue created in a weekly continuous integration job 🤖.**
+
+This issue contains a list of links external to The Turing Way that appeared to be broken when the check was last run.
+
+**The conversation on this issue has been locked.**
+This is because the list of broken links will change whenever the job is run, so this is not a good place to discuss particular links.
+
+## Understanding the Errors
+
+### Locating Errors
+
+Errors are grouped by the output html pages they appear in.
+
+The paths of these pages after `book/website/_build/html` correspond to their source Markdown files.
+For example, `book/website/_build/html/reproducible-research/vcs/vcs-workflow.html` corresponds to `book/website/reproducible-research/vcs/vcs-workflow.md`.
+Broken links can be fixed in the Markdown file.
+
+### False Negatives
+
+The list of error **will contain false negatives**.
+Some domains will interpret the link checker as a possible denial of service attack, especially if it makes multiple requests.
+Others may require authentication for particular pages.
+The link checker may then be unable to verify that certain links works.
+
+If certain domains are repeatedly producing false negatives they can be ignored by adding an entry to the `exclude` list in the [Lychee configuration file](https://github.com/alan-turing-institute/the-turing-way/blob/main/lychee.toml).
+
+### Link Status
+
+Each failing link is presented with its status which is either a string like `ERR`, `TIMEOUT` or a HTTP response status code like `404`.
+Mozilla has a [guide to HTTP response codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) which can help explain the codes in the list.
+
+Here are some rules of thumb.
+These are quite likely to be false negatives,
+
+- 403
+- TIMEOUT
+
+These are quite likely to be genuine problems,
+
+- 404
+- ERR
+- 50? (500, 501, 502, _etc._)

.github/workflows/yamllint.yaml

@@ -1,6 +1,10 @@
 name: Lint and Validate YAML files
 
 on:
+  pull_request:
+    paths:
+      - "**.yaml"
+      - "**.yml"
   push:
     paths:
       - "**.yaml"

CONTRIBUTING.md

@@ -303,7 +303,7 @@ What happens if the continuous integration (CI) fails (for example, if the pull
 The CI could fail for a number of reasons.
 At the bottom of the pull request, where it says whether your build passed or failed, you can click “Details” next to the test, which takes you to a CI run log site.
 If you have the write access to the repo, you can view the log or rerun the checks by clicking the “Restart build” button in the top right.
-You can learn more about CI in the {ref}`Continuous Integration chapter<rr-ci>`!
+You can learn more about CI in the [Continuous Integration chapter](https://the-turing-way.netlify.app/reproducible-research/ci.html)!
 
 GitHub has a [nice introduction][github-flow] to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions :balloon:.