From 426db88ff35e6443ee9247e34525499b05a7acca Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Fri, 23 Jan 2026 10:02:00 -0500 Subject: [PATCH 1/8] ci: don't fail build for invalid urls --- .github/matcher-htmlproofer.json | 14 ++++++++++++++ .github/workflows/ci.yml | 6 ++++++ REUSE.toml | 8 ++++++++ mkdocs.yml | 12 ++++-------- 4 files changed, 32 insertions(+), 8 deletions(-) create mode 100644 .github/matcher-htmlproofer.json diff --git a/.github/matcher-htmlproofer.json b/.github/matcher-htmlproofer.json new file mode 100644 index 00000000..62e3899c --- /dev/null +++ b/.github/matcher-htmlproofer.json @@ -0,0 +1,14 @@ +{ + "problemMatcher": [ + { + "owner": "htmlproofer", + "pattern": [ + { + "regexp": "^WARNING - htmlproofer: (invalid url - .+ \\[.+\\]) \\[(.+)\\]$", + "file": 2, + "message": 1 + } + ] + } + ] +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index adfd1c78..60d477f1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -84,6 +84,12 @@ jobs: path: .cache restore-keys: | mkdocs-material- + # Problem matcher for htmlproofer warnings (instead of errors to avoid failing the build randomly) + # https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md + # https://github.com/actions/toolkit/blob/main/docs/commands.md#problem-matchers + - name: Add problem matcher + run: | + echo "::add-matcher::.github/matcher-htmlproofer.json" - name: Build site run: uv run mkdocs build --strict diff --git a/REUSE.toml b/REUSE.toml index 00f9a9e9..9cccb372 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -28,6 +28,14 @@ precedence = "override" SPDX-FileCopyrightText = "Copyright (C) 2022 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre " SPDX-License-Identifier = "MIT" +[[annotations]] +path = [ + ".github/matcher-htmlproofer.json", +] +precedence = "override" +SPDX-FileCopyrightText = "Copyright (C) 2026 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre " +SPDX-License-Identifier = "MIT" + [[annotations]] path = [ ".vscode/C4.code-snippets", diff --git a/mkdocs.yml b/mkdocs.yml index 7a5d9f96..9e0e3c9a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -110,7 +110,7 @@ plugins: - privacy # https://github.com/manuzhang/mkdocs-htmlproofer-plugin#configuring - htmlproofer: - raise_error: True + raise_error: False raise_error_excludes: # some URLs sporadically return a 504 (Gateway Timeout) 504: ["*"] @@ -118,18 +118,14 @@ plugins: 429: ["*"] skip_downloads: True ignore_urls: - # non-public URLs - - https://docs.opalmedapps.ca/* - - https://opalmedapps.gitlab.io/* - # - https://github.com/opalmedapps/* # PlantUML diagrams are included as data - "data:*" # Twitter URL sometimes returns a 404 - https://x.com/i_a_r_n_a/status/623922369376202758 # all below use Cloudflare which returns a captcha first with a 403 - - https://towardsdatascience.com/type-hints-in-python-everything-you-need-to-know-in-5-minutes-24e0bad06d0b - - https://www.npmjs.com/package/* - - https://dianadarie.medium.com/the-strangler-fig-migration-pattern-2e20a7350511 + # - https://towardsdatascience.com/type-hints-in-python-everything-you-need-to-know-in-5-minutes-24e0bad06d0b + # - https://www.npmjs.com/package/* + # - https://dianadarie.medium.com/the-strangler-fig-migration-pattern-2e20a7350511 # only enable when building in CI to speed up local builds enabled: !ENV [CI, false] From 03d538e4f8a37af4e3b65cfd538e7efffccaca02 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Fri, 23 Jan 2026 10:16:56 -0500 Subject: [PATCH 2/8] ci: don't fail build for invalid urls --- .github/matcher-htmlproofer.json | 3 ++- .github/workflows/ci.yml | 4 +--- mkdocs.yml | 9 +++++---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/matcher-htmlproofer.json b/.github/matcher-htmlproofer.json index 62e3899c..12e44ad0 100644 --- a/.github/matcher-htmlproofer.json +++ b/.github/matcher-htmlproofer.json @@ -1,10 +1,11 @@ { + "__comment": "Docs: https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md", "problemMatcher": [ { "owner": "htmlproofer", "pattern": [ { - "regexp": "^WARNING - htmlproofer: (invalid url - .+ \\[.+\\]) \\[(.+)\\]$", + "regexp": "^ERROR - htmlproofer: (invalid url - .+ \\[.+\\]) \\[(.+)\\]$", "file": 2, "message": 1 } diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 60d477f1..a1801dec 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -84,10 +84,8 @@ jobs: path: .cache restore-keys: | mkdocs-material- - # Problem matcher for htmlproofer warnings (instead of errors to avoid failing the build randomly) - # https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md # https://github.com/actions/toolkit/blob/main/docs/commands.md#problem-matchers - - name: Add problem matcher + - name: Add problem matcher for HTML proofer invalid url errors run: | echo "::add-matcher::.github/matcher-htmlproofer.json" - name: Build site diff --git a/mkdocs.yml b/mkdocs.yml index 9e0e3c9a..9024c15d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -110,7 +110,8 @@ plugins: - privacy # https://github.com/manuzhang/mkdocs-htmlproofer-plugin#configuring - htmlproofer: - raise_error: False + # check all URLs before raising an error + raise_error_after_finish: True raise_error_excludes: # some URLs sporadically return a 504 (Gateway Timeout) 504: ["*"] @@ -123,9 +124,9 @@ plugins: # Twitter URL sometimes returns a 404 - https://x.com/i_a_r_n_a/status/623922369376202758 # all below use Cloudflare which returns a captcha first with a 403 - # - https://towardsdatascience.com/type-hints-in-python-everything-you-need-to-know-in-5-minutes-24e0bad06d0b - # - https://www.npmjs.com/package/* - # - https://dianadarie.medium.com/the-strangler-fig-migration-pattern-2e20a7350511 + - https://towardsdatascience.com/type-hints-in-python-everything-you-need-to-know-in-5-minutes-24e0bad06d0b + - https://www.npmjs.com/package/* + - https://dianadarie.medium.com/the-strangler-fig-migration-pattern-2e20a7350511 # only enable when building in CI to speed up local builds enabled: !ENV [CI, false] From 876f155b849b84cf7f6a06cea3f507408d50f962 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Fri, 23 Jan 2026 10:26:09 -0500 Subject: [PATCH 3/8] fix problem matcher --- .github/matcher-htmlproofer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/matcher-htmlproofer.json b/.github/matcher-htmlproofer.json index 12e44ad0..ab46a46d 100644 --- a/.github/matcher-htmlproofer.json +++ b/.github/matcher-htmlproofer.json @@ -5,7 +5,7 @@ "owner": "htmlproofer", "pattern": [ { - "regexp": "^ERROR - htmlproofer: (invalid url - .+ \\[.+\\]) \\[(.+)\\]$", + "regexp": "^ERROR\\s+-\\s+htmlproofer: (invalid url - .+ \\[.+\\]) \\[(.+)\\]$", "file": 2, "message": 1 } From 7820cdf28ea5ab4a70e8043f7c46597f67c7c855 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Fri, 23 Jan 2026 10:34:36 -0500 Subject: [PATCH 4/8] test --- .github/workflows/ci.yml | 4 ++++ zizmor.yml | 2 ++ 2 files changed, 6 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a1801dec..8599fc7c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -90,6 +90,10 @@ jobs: echo "::add-matcher::.github/matcher-htmlproofer.json" - name: Build site run: uv run mkdocs build --strict + - name: View context attributes + uses: actions/github-script@v8 + with: + script: console.log(context) deploy: uses: ./.github/workflows/deploy.yml diff --git a/zizmor.yml b/zizmor.yml index d8285efa..11f4be6c 100644 --- a/zizmor.yml +++ b/zizmor.yml @@ -7,3 +7,5 @@ rules: config: policies: opalmedapps/*: ref-pin + # for testing + actions/github-script: ref-pin From dac11847666705e8b2be5babde92595b3a26386e Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Fri, 23 Jan 2026 10:36:47 -0500 Subject: [PATCH 5/8] test --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8599fc7c..125d62f3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -92,6 +92,7 @@ jobs: run: uv run mkdocs build --strict - name: View context attributes uses: actions/github-script@v8 + if: '!cancelled()' with: script: console.log(context) From 6ea68c5f1d6d348cdbce6c0dc92717b45199c8ac Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Fri, 23 Jan 2026 10:37:58 -0500 Subject: [PATCH 6/8] revert archived URL --- docs/development/architecture/migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/architecture/migration.md b/docs/development/architecture/migration.md index c2111c3f..fac256f5 100644 --- a/docs/development/architecture/migration.md +++ b/docs/development/architecture/migration.md @@ -33,7 +33,7 @@ More details about this pattern can be found in the resources below. - [The Strangler Fig Migration Pattern | by Diana Darie | Medium](https://dianadarie.medium.com/the-strangler-fig-migration-pattern-2e20a7350511) - [The Strangler pattern in practice - Michiel Rook's blog](https://www.michielrook.nl/2016/11/strangler-pattern-practice/) - [What is the Strangler Fig Pattern and How it Helps Manage Legacy Code](https://www.freecodecamp.org/news/what-is-the-strangler-pattern-in-software-development/) -- [The Ship of Theseus to NOT rewrite a legacy system from scratch](https://web.archive.org/web/20241209060056/https://understandlegacycode.com/blog/ship-of-theseus-avoid-rewrite-legacy-system/) +- [The Ship of Theseus to NOT rewrite a legacy system from scratch](https://understandlegacycode.com/blog/ship-of-theseus-avoid-rewrite-legacy-system/) - [https://docs.microsoft.com/en-us/azure/architecture/patterns/strangler-fig](https://docs.microsoft.com/en-us/azure/architecture/patterns/strangler-fig) ## Migration Process From 5b27b75c11fc61723d817e81d20e6b69e8fcea17 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Fri, 23 Jan 2026 10:40:16 -0500 Subject: [PATCH 7/8] revert test --- .github/workflows/ci.yml | 5 ----- zizmor.yml | 2 -- 2 files changed, 7 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 125d62f3..a1801dec 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -90,11 +90,6 @@ jobs: echo "::add-matcher::.github/matcher-htmlproofer.json" - name: Build site run: uv run mkdocs build --strict - - name: View context attributes - uses: actions/github-script@v8 - if: '!cancelled()' - with: - script: console.log(context) deploy: uses: ./.github/workflows/deploy.yml diff --git a/zizmor.yml b/zizmor.yml index 11f4be6c..d8285efa 100644 --- a/zizmor.yml +++ b/zizmor.yml @@ -7,5 +7,3 @@ rules: config: policies: opalmedapps/*: ref-pin - # for testing - actions/github-script: ref-pin From 12512aa5dd9c064dceb52a1247e1d22d0ae5ae37 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Fri, 23 Jan 2026 10:50:16 -0500 Subject: [PATCH 8/8] replace URL with archived version --- docs/development/best_practices/code_review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/best_practices/code_review.md b/docs/development/best_practices/code_review.md index 04f15538..00478a82 100644 --- a/docs/development/best_practices/code_review.md +++ b/docs/development/best_practices/code_review.md @@ -172,6 +172,6 @@ The below list contains extra resources that may be of interest: [^talk]: Presentation and slides on "Code Review Skills for Pythonistas": https://www.nnja.io/post/2018/2018-djangocon-code-review/ -[^phauer]: Code Review Guidelines for Humans: https://phauer.com/2018/code-review-guidelines/ +[^phauer]: Code Review Guidelines for Humans: https://web.archive.org/web/20250623040639/https://phauer.com/2018/code-review-guidelines/ [^twitter]: Rebecca's Rules for Constructive Code Reviews - Twitter: https://x.com/i_a_r_n_a/status/623922369376202758