Existing use of Hugo aliases risks overlap and redirects going to wrong page

[enj]

A change made in #43368 broke the https://kubernetes.io/security and other aliases because it also set them for the RU pages. This should ideally fail in CI and during local dev, as it is an easy mistake to make, and difficult to catch during code review.

Wow, on behalf of the Russian localisation team, I want to apologise for such an omission on our side! 😢 That happened in #43368. I found a similar issue with /cve, which should be fixed in #46293.

P.S. I also grep'ed all other languages for aliases: and didn't find similar issues.

No worries, this type of stuff is easy to miss.

I don't know if it is possible, but perhaps we should have some kind of linter that validates that aliases don't overlap?

Originally posted by @enj in #46281 (comment)

[shannonxtreme]

/triage accepted
/sig docs
/language ru
/language en

[shannonxtreme]

@enj if #46281 fixed this you can close the issue :) Thank you for raising this!

[enj]

@enj if #46281 fixed this you can close the issue :) Thank you for raising this!

This issue is about adding new checks to prevent the same bug from happening again. That PR just fixed a specific instance of the bug.

[shurup]

Thanks for raising this issue, @enj!

Since we don't have any linting at the moment, I think it would be reasonable to find other similar cases where we might benefit. If we make a more extensive list, we'll better understand what is needed in the end, yet we can still start from the most essential cases. Here are a few examples that come to my mind based on my experience in localisation:

1. For translated pages, check all the /docs/… links in the text to see whether a relevant /<LANG>/docs/… page exists. (We should change such links to their translated versions, then.) The opposite — the /<LANG>/docs/ links leading to non-existing pages — should be checked as well.
2. Incorrect syntax — e.g., unclosed tags (update scale-intro.html (close <code> tag) #45380).
3. Some extra checks for metadata. Do we need to have reviewers for the localised pages? Do we need to keep all other metadata fields (content_type, weight…) for the localised pages in sync with the original?
4. Perhaps some checks for glossary tooltips and included pages? Both should exist if they are referred to.

[sftim]

This issue suggests a particular fix (and not the one I'd pick). @enj if you're willing to pick a different issue title, please do.

The problem is that aliases can overlap silently, and this can break existing redirects. It's easy for a localization team to miss that they've done this. How I'd solve it: build the _redirects file that Netlify consumes using Hugo templating, and have Hugo - not a linter - check that there are no overlaps.
Hugo could also require that a particular localization never tries to redirect from a different localization, or we can even define the data format so it's not actually possible to do that.

Likely outcomes for the approach I advocate:

• even a local development build would fail if there were two conflicting redirects
• localizations could manage their own redirects, rather than needing site-wide approval
• we'd merge two existing page alias mechanisms into one
• the problem that this issue highlights now can't happen
• we can more easily enable automating other related features, such as Netlify reverse proxying

I've seen this done by other Hugo sites that use Netlify, so it's new ground but new-for-SIG-Docs not new-for-the-world. We can borrow ideas from existing open source docs sites and wouldn't have to invent a new thing from scratch.

[sftim]

/priority important-longterm

[enj]

@sftim I took a shot at updating the title of the issue, please feel free to edit.

[sftim]

/retitle Existing use of Hugo aliases risks overlap and redirects going to wrong page