search

kubernetes-sigs / prow

Prow is a Kubernetes based CI/CD system developed to serve the Kubernetes community. This repository contains Prow source code and Hugo sources for Prow documentation site.
https://docs.prow.k8s.io
Apache License 2.0
109 stars 90 forks source link

Implement doc checkers #5

Open listx opened 2 years ago

listx commented 2 years ago

Reference: https://github.com/kubernetes/test-infra/issues/24821#issuecomment-1057524854

As per the design doc, we should implement automated checkers to make sure we uphold minimum quality standard for both existing documentation as well as newly proposed documentation.

There have been some discussions in the design doc already, but feel free to comment on here about which checker(s) to implement first.

k8s-triage-robot commented 2 years ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

k8s-triage-robot commented 2 years ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

k8s-triage-robot commented 2 years ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

k8s-ci-robot commented 2 years ago

@k8s-triage-robot: Closing this issue.

In response to [this](https://github.com/kubernetes-sigs/prow/issues/5#issuecomment-1200327577): >The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. > >This bot triages issues and PRs according to the following rules: >- After 90d of inactivity, `lifecycle/stale` is applied >- After 30d of inactivity since `lifecycle/stale` was applied, `lifecycle/rotten` is applied >- After 30d of inactivity since `lifecycle/rotten` was applied, the issue is closed > >You can: >- Reopen this issue or PR with `/reopen` >- Mark this issue or PR as fresh with `/remove-lifecycle rotten` >- Offer to help out with [Issue Triage][1] > >Please send feedback to sig-contributor-experience at [kubernetes/community](https://github.com/kubernetes/community). > >/close > >[1]: https://www.kubernetes.dev/docs/guide/issue-triage/ Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
jihoon-seo commented 1 year ago

/reopen /lifecycle frozen

Here are tools I saw:

  1. K8s doc's Internal link checking tool

According to the doc, the tool

and its workflow seems similar to the current link checker in this Prow doc repo. https://github.com/kubernetes-sigs/prow/blob/0d8946d8dccdcbbb1dc00c3c20641b202b0494a8/site/Makefile#L26-L27 https://github.com/kubernetes-sigs/prow/blob/0d8946d8dccdcbbb1dc00c3c20641b202b0494a8/site/check-broken-links.sh#L22-L30

  1. K8s doc's linkchecker.py

While the above linkcheckers analyze whether the links in the Hugo-generated HTML files are working or not (404, ...), this linkchecker performs sort of static analysis on markdown files.

And yes, it would be great to implement a new linkchecking Prow workflow

k8s-ci-robot commented 1 year ago

@jihoon-seo: You can't reopen an issue/PR unless you authored it or you are a collaborator.

In response to [this](https://github.com/kubernetes-sigs/prow/issues/5#issuecomment-1324798937): >/reopen >/lifecycle frozen > >Here are tools I saw: > >1. K8s doc's [Internal link checking tool](https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools/linkchecker) > >According to the doc, the tool >- Builds the site and generates output HTML in the `/public` directory of your local `kubernetes/website` repository >- Pulls the `wdjp/htmltest` Docker image >- Mounts your local `kubernetes/website` repository to the Docker image >- Scans the files generated in the `/public` directory and provides command line output when it encounters broken internal links > >and its workflow seems similar to the current link checker in this Prow doc repo. >https://github.com/kubernetes-sigs/prow/blob/0d8946d8dccdcbbb1dc00c3c20641b202b0494a8/site/Makefile#L26-L27 >https://github.com/kubernetes-sigs/prow/blob/0d8946d8dccdcbbb1dc00c3c20641b202b0494a8/site/check-broken-links.sh#L22-L30 > >--- > >2. K8s doc's [`linkchecker.py`](https://github.com/kubernetes/website/tree/main/scripts#linkcheckerpy) > >While the above linkcheckers analyze whether the links in the Hugo-generated HTML files are working or not (404, ...), >this linkchecker performs sort of static analysis on markdown files. > >--- > >And yes, it would be great to implement a new linkchecking Prow workflow >- for every PR, and/or >- executed periodically Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
petr-muller commented 1 year ago

/reopen

Does not feel like an issue that should rot - either we think this is useful, or we should explicitly decide we don't want that.

k8s-ci-robot commented 1 year ago

@petr-muller: Reopened this issue.

In response to [this](https://github.com/kubernetes-sigs/prow/issues/5#issuecomment-1324929151): >/reopen > >Does not feel like an issue that should rot - either we think this is useful, or we should explicitly decide we don't want that. Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
listx commented 1 year ago

I think the first option (https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools/linkchecker) could be adopted. It is simpler as it already uses the same underlying tool (htmltest) that we currently use.

The first step is to add it as a CI job (either the same link checker as used in kubernetes/website or the existing Make rule we have). I don't think it makes sense to add it as a presubmit as links can break sporadically. Probably running the job 2x a day would be good so that we can get some signal that all links are OK.