MILV, a tool introduced to detect broken links in Kyma documentation in the kyma-project repositories, has a bug. As there is no person responsible for maintaining the tool, all governance jobs that use it are failing. Huskies conducted a PoC and integrated a GitHub Action for checking links in markdown files in the /telemetry-manager repo. It uses the Markdown link check from the GitHub Actions Marketplace. The PoC implementation was successful. The solution has one drawback, namely, the HTTP links anchors are not validated.
Decision
Broken links mean a bad user experience. To ensure high product quality, documentation links need to be working properly. The decision is to introduce an obligatory Markdown link check in the kyma-project repositories. Using that tool will ensure broken link detection and will oblige PR creators to fix broken links before merging their PRs. For more configuration details see the PoC outcome, the official Markdown link check documentation, and the official GitHub Action - Markdown link check documentation.
The check should be conducted on two levels.
PR level - checking links in markdown files being part of the created PR
Repository level - checking links in all markdown files in a repository. This would be a periodic, daily check scheduled on the main branch. Read more details on how to schedule GitHub Actions.
Consequences
Repository owners will be responsible for the maintenance of the Markdown link check.
@kyma-project/technical-writers will be responsible for the maintenance of the Markdown link check configuration files for the /kyma repository.
mmitoraj
commented
1 year ago
Created on 2023-08-17 by Małgorzata Świeca (@mmitoraj).
Decision log
Context
MILV, a tool introduced to detect broken links in Kyma documentation in the
kyma-projectrepositories, has a bug. As there is no person responsible for maintaining the tool, all governance jobs that use it are failing. Huskies conducted a PoC and integrated a GitHub Action for checking links in markdown files in the/telemetry-managerrepo. It uses the Markdown link check from the GitHub Actions Marketplace. The PoC implementation was successful. The solution has one drawback, namely, the HTTP links anchors are not validated.Decision
Broken links mean a bad user experience. To ensure high product quality, documentation links need to be working properly. The decision is to introduce an obligatory Markdown link check in the
kyma-projectrepositories. Using that tool will ensure broken link detection and will oblige PR creators to fix broken links before merging their PRs. For more configuration details see the PoC outcome, the official Markdown link check documentation, and the official GitHub Action - Markdown link check documentation.The check should be conducted on two levels.
Consequences
/kymarepository.governancejobs will be removed