diff --git a/.github/workflows/check-links.yaml b/.github/workflows/check-links.yaml new file mode 100644 index 00000000000..7dada028ff3 --- /dev/null +++ b/.github/workflows/check-links.yaml @@ -0,0 +1,20 @@ +name: Check external href links in the documentation + +on: + schedule: + # Run on the first of each month at 9:00 AM (See https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07) + - cron: "0 9 1 * *" + +jobs: + markdown-link-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@master + - name: Prepare markdown-link-check + run: mkdir docs/ROOT && cp CHANGELOG.md README.md docs/ROOT + - uses: gaurav-nelson/github-action-markdown-link-check@v1 + with: + use-quiet-mode: 'yes' + use-verbose-mode: 'no' + config-file: 'mlc_config.json' + folder-path: 'docs/' diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 1262b90b6da..d2568960878 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -44,15 +44,6 @@ jobs: with: args: CHANGELOG.md CONTRIBUTING.md README.md docs/ config: '.markdownlint.yml' - - name: Prepare markdown-link-check - run: mkdir docs/ROOT && cp CHANGELOG.md README.md docs/ROOT - - name: Run markdown-link-check - uses: gaurav-nelson/github-action-markdown-link-check@v1 - with: - use-quiet-mode: 'yes' - use-verbose-mode: 'no' - config-file: 'mlc_config.json' - folder-path: 'docs/' tests: name: Unit tests runs-on: ubuntu-latest diff --git a/docs/adr/0011-test-external-links-in-documentation.md b/docs/adr/0011-test-external-links-in-documentation.md new file mode 100644 index 00000000000..b1b9756e799 --- /dev/null +++ b/docs/adr/0011-test-external-links-in-documentation.md @@ -0,0 +1,47 @@ +# Test external links in documentation + +## Context and Problem Statement + +The JabRef repository contains Markdown (`.md`) files documenting the JabRef code. +The documentation contains links to external resources. +For high-quality documentation, external links should be working. + +## Decision Drivers + +* Checking external links should not cause issues in the normal workflow + +## Considered Options + +* Check external links once a month +* Check external links in the "checkstyle" task +* Do not check external links + +## Decision Outcome + +Chosen option: "\[option 1\]", because \[justification. e.g., only option, which meets k.o. criterion decision driver \| which resolves force force \| … \| comes out best \(see below\)\]. + +### Positive Consequences + +* Automatic notification of broken external links + +### Negative Consequences + +* Some external sites need to [be disabled](https://github.com/JabRef/jabref/pull/6542/files). For isntance, GitHub.com always returns "forbidden". A [filter for status is future work of the used tool](https://github.com/tcort/markdown-link-check/issues/94#issuecomment-634947466). + +## Pros and Cons of the Options + +### Check external links once a month + +* Good, because does not interfer with the normal development workflow +* Bad, because an additional workflow is required + +### Check external links in the "checkstyle" task + +* Good, because no seperate workflow is required +* Bad, because checks fail independent of the PR (because external web sites can go down and go up independent of a PR) + +### Do not check external links + +* Good, because no testing at all is required +* Bad, because external links break without any notice +* Bad, because external links have to be checked manually