You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2023/01/06 03:07:07 UTC
[GitHub] [pulsar] Anonymitaet created a discussion: [feat] add dead link checker to CI/CD
GitHub user Anonymitaet created a discussion: [feat] add dead link checker to CI/CD
### Search before asking
- [X] I searched in the [issues](https://github.com/apache/pulsar/issues) and found nothing similar.
### Motivation
# 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 do not 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
# Solution
Can we implement a `dead link check` to the CI/CD process in `pulsar-site`?
### Example
Skywalking
<img width="1017" alt="image" src="https://user-images.githubusercontent.com/50226895/210919627-62826cd9-8998-4169-8fa8-3eba19cd73b2.png">
### 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
### Alternatives
N/A
### Anything else?
N/A
### Are you willing to submit a PR?
- [ ] I'm willing to submit a PR!
GitHub link: https://github.com/apache/pulsar/discussions/19144
----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org
[GitHub] [pulsar] tisonkun added a comment to the discussion: [feat] add dead link checker to CI/CD
Posted by GitBox <gi...@apache.org>.
GitHub user tisonkun added a comment to the discussion: [feat] add dead link checker to CI/CD
FYI: I'm going to enable Docusaurus builtin broken links checker in the site repo in this month.
* https://docusaurus.io/docs/api/docusaurus-config#onBrokenLinks
* https://docusaurus.io/docs/api/docusaurus-config#onBrokenMarkdownLinks
I'll enable the warning level first to get a report and see how to fix.
Other integrations proposed here can be good to have a try. But I think we should enable them on the site repo, right?
GitHub link: https://github.com/apache/pulsar/discussions/19144#discussioncomment-4607935
----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org
[GitHub] [pulsar] tisonkun added a comment to the discussion: [feat] add dead link checker to CI/CD
Posted by GitBox <gi...@apache.org>.
GitHub user tisonkun added a comment to the discussion: [feat] add dead link checker to CI/CD
> Does the detection happen during the local preview
Yes. It will.
GitHub link: https://github.com/apache/pulsar/discussions/19144#discussioncomment-4607990
----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org
[GitHub] [pulsar] momo-jun added a comment to the discussion: [feat] add dead link checker to CI/CD
Posted by GitBox <gi...@apache.org>.
GitHub user momo-jun added a comment to the discussion: [feat] add dead link checker to CI/CD
The Docu built-in checker sounds better. Does the detection happen during the local preview?
If yes, it would be more proactive than a checker in the CI/CD process. But on the other hand, not all contributors run the local preview. It's not a mandatory step for minor fixes. The checker integrated in the CI/CD process can be a gate for this.
GitHub link: https://github.com/apache/pulsar/discussions/19144#discussioncomment-4607962
----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org
[GitHub] [pulsar] Anonymitaet added a comment to the discussion: [feat] add dead link checker to CI/CD
Posted by GitBox <gi...@apache.org>.
GitHub user Anonymitaet added a comment to the discussion: [feat] add dead link checker to CI/CD
> I think we should enable them on the site repo, right?
Yes
GitHub link: https://github.com/apache/pulsar/discussions/19144#discussioncomment-4608664
----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org
[GitHub] [pulsar] Anonymitaet edited a discussion: [feat] add dead link checker to CI/CD
Posted by GitBox <gi...@apache.org>.
GitHub user Anonymitaet edited a discussion: [feat] add dead link checker to CI/CD
# 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
<img width="1017" alt="image" src="https://user-images.githubusercontent.com/50226895/210919627-62826cd9-8998-4169-8fa8-3eba19cd73b2.png">
### 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
GitHub link: https://github.com/apache/pulsar/discussions/19144
----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org