Skip to main content Link Menu Expand (external link) Document Search Copy Copied

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

Pros and Cons of the Options

  • Good, because does not interfere with the normal development workflow
  • Bad, because an additional workflow is required
  • 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)
  • 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