52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
---
|
|
parent: Decision Records
|
|
nav_order: 11
|
|
---
|
|
# 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 instance, 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 interfere with the normal development workflow
|
|
* Bad, because an additional workflow is required
|
|
|
|
### Check external links in the "checkstyle" task
|
|
|
|
* Good, because no separate 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
|