apache / apache/pulsar

[feat][workflow] add dead link checker to CI/CD

Open
#19,658 2 comments 0 reactions 0 assignees View on GitHub
area/ci doc Stale type/feature
Dominant language
Java
Stars
15.3k
Forks
3.8k
Avg merge
1d 14h
Merged PRs (30d)
160

Description

### Discussed in https://github.com/apache/pulsar/discussions/19144

Originally posted by **Anonymitaet** January 6, 2023
# Issue

Sometimes 404 errors occur in docs.

Currently, we use the following ways to check them:

### Method 1: use tools to check them manually at regular intervals

- [Dr. Link Checker](https://www.drlinkcheck.com/)

- [W3C Link Checker](https://validator.w3.org/checklink?uri=http%3A%2F%2Fpulsar.apache.org%2Fdocs&hide_type=all&recursive=on&depth=4&check=Check)

- [Dead Link Checker](https://www.deadlinkchecker.com/)

#### Disadvantages

- It's easy to forget to do this task.

- It entirely depends on the contributor's willingness.

### Method 2: check the links through the local preview process

It reminds you of 404 errors if any.

#### Disadvantages

- Some contributors need to preview docs on the local machines and the link check step is skipped.

- Even though contributors preview docs and get reminders of 404 issues, they can ignore this error and still submit doc PRs.

# Solution

Can we implement a `dead link check` to the CI/CD process in `pulsar-site`?

### Example

Skywalking
image

### Benefits

- Docs submitted from all contributors can be checked in a prominent and easy way

- If we want to ensure no 404 links in docs, we can set this check as `required`. In this way, PRs can not be merged with 404 issues.

- (Other doc-related checks, e.g., **grammar checks, typo checks**, etc can also be implemented)

cc @momo-jun @DaveDuggins @D-2-Ed

Contributor guide

Open the contributing guide

Research direction

Start by inspecting the CI/CD workflows and documentation preview process in pulsar-site, which the issue identifies as the target. Determine how a dead-link check could fit into that process; done means documentation links are checked through CI/CD and failures are visible to contributors.

Written by the indexing model from the issue text.

Assessment

Domain
ci-cd, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.