53 lines
1.7 KiB
Markdown
53 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: "Check external links once a month", because it provides a basic quality baseline.
|
|
|
|
### 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".
|
|
* Contributors find it strange if external links are broken (example: [user-documentation#526](https://github.com/JabRef/user-documentation/pull/526#issuecomment-2416462977))
|
|
|
|
## 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
|