[chore] run markdown-link-check on version change

[niwoerner]

Description

This PR will run the "markdown-link-check" tool if the version of the tool changes even if no markdown files were updated. This will help to confirm that "markdown-link-check" is still working as expected after a version update/pin.

If 1+ *.md files gets changed AND the version gets updated, it will only check the updated files to keep the same behaviour as before.

If only the version gets updated it will test all existing *.md files.

EDIT:

After feedback and suggestion from @mowies (thank you again! :) ), I switched to use a predefined github action which checks markdown files changes AND if the .github/workflows/check-links.yaml changed.

If the '.github/workflows/check-links.yaml' file, the markdown-link-check tool will test against all markdown files existing in the repo. This would catch a version change of the "markdown-link-check" tool and test it accordingly.

If 1+ *.md file gets changed while the .github/workflows/check-links.yaml file does not change, it will only test the changed files to keep the same behaviour like before.

/cc @mx-psi @mowies @ChrsMark

Link to tracking issue

Fixes #36588

[mowies]

Instead having fairly complicated bash scripting, why not simplify the whole thing a bit by just checking if the whole file changed and using that as a trigger? I don't think it will hurt in terms of github runner busyness and I would expect that to be better from a maintainability POV. WDYT?

[fatsheep9146]

Could you help resolve the conflicts?

[mowies]

i guess the dead links could also be fixed in this PR. i'm counting 7 issues with links from the check. (search for error: in the logs)

[niwoerner]

With this PR we will scan all markdown files on a potential version change of the "markdown-link-check" tool. If 1+ markdown files get changed, it will only check the changed files and not all.

Since we didn't run the check recursively on all markdown files before, this reveals several broken links and causes the check-links action to fail. (while doing what it should)

Are there any opinions on how we should handle this?

I could think about:

1. Only scanning a handful markdown files (e.g all md files in the top-level directory)
2. Adding an automation for tracking broken links in an automatically created file (or perhaps directly creating issues?) and marking the "failed" check-links action with a warning
3. Accepting the broken links and marking the "failed" action with a warning (they are probably broken since a longer time, but simply unnoticed)

I think checking all markdown files recursively from time to time makes sense to reveal such dead links which were missed before. But I'm not sure about the best way to handle it from a maintenance perspective.

Option 2 with tracking the dead links in a file might be the best of both worlds. Not too much noise about broken links, but still clear visibility what should be fixed.

Maybe someone else has additional thoughts on it?

/cc @mx-psi @mowies @ChrsMark

[niwoerner]

i guess the dead links could also be fixed in this PR. i'm counting 7 issues with links from the check. (search for error: in the logs)

I think fixing them manually as part of this PR will only help temporarily until we run a full check the next time and might discover new broken links. If I find the correct links, I can try to fix them as part of this PR, but the same problem could come up in the future again I fear

[mowies]

are we not already checking all markdown files now with the find implementation? if not, i think we should.

[niwoerner]

are we not already checking all markdown files now with the find implementation? if not, i think we should.

yes, we are. I was thinking about how we should handle the now uncovered broken links since we run the check on all files

[mowies]

ok, i think we should just fix them, it's not that many :)
new ones won't come up as soon as this is merged since the check will fail every time. (assuming that this PR check is set to "required")

[niwoerner]

ok, i think we should just fix them, it's not that many :) new ones won't come up as soon as this is merged since the check will fail every time. (assuming that this PR check is set to "required")

Ok, im fine with that 👍 - But it could happen that new ones come up if it takes some time until we run the check on all files again. As of now we would only do that if the check-links.yaml changes, but not always as soon as a markdown file changes.

Shouldn't be much new broken links the next time though (hopefully) 😄

[ArthurSens]

LGTM for the file changes in the prometheus translator. Thanks for fixing them!

[ChrsMark]

It seems we still get some errors from links. I re-run the test to check if it was just temporary "flakiness" but didn't help. Is the intention to fix them?

[niwoerner]

@ChrsMark Yes, I will look into the other broken links later today (or tomorrow) and try to find a solution for them. At a first glance some of them seem to fail in CI but working when opening via the browser. We might need to handle them via the markdown-link-check config. But I need a bit more time to confirm that

[niwoerner]

All broken links should be handled correctly now. The markdown-link-check succeeds for all found links: https://github.com/open-telemetry/opentelemetry-collector-contrib/actions/runs/12261838409?pr=36645

-> I had to add the oracle link to the ignored links, because Akami seems to block the requests, although the link itself works in the browser. Adding headers to potentially bypass the DoS protection with something like the curl test below wasn't fixing it unfortunately:

curl -s -I \
-H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36" \
-H "Accept-Encoding: gzip, deflate, br" \
https://blogs.oracle.com/developers/post/connecting-a-go-application-to-oracle-database