locale (en-us) links go undetected in source code

[maorleger]

I was looking into any instances where we have a locale link (en-us in the URL) and noticed that there are many such links in source code. I know our aggregate pipelines currently detect and warn against such links in markdown files (with a warning: DO NOT include locale /en-us/ information in links) - I believe it's a miss that we currently do not validate source code, although maybe there are technical reasons I am not aware of?

[weshaggard]

We have a similar issue in .NET repo Azure/azure-sdk-for-net#22216

The biggest issue is we don't have a great way to find all the links in a JS file. Parsing the entire text and looking for links might be overkill as there might be lots of code that looks like it is a link but isn't. If you can help come up with a strategy that allows us to find the list of links we could then feed them into our link-verify script and have them validated.

[jeremymeng]

We could probably do some minimum work via eslint rule? like matching strings having both https://docs.microsoft.com/ and en-us

[maorleger]

@jeremymeng I think that's a great idea! it'll be flagged in PRs and easy to skip per-line due to any false-positives. Although I would say anything with http:.*/en-us/.* (we can refine it a bit of course) we can flag as we have many MDN links which also can contain locale information. That might get us like 80-90% of the way there to be honest which is progress...

[weshaggard]

While checking en-us is good but I assume these will turn into real links in the ref docs so we should try and figure out a way to check that the links are valid.

[weshaggard]

As part of our builds don't we produce the ref docs as html? If so we could pass the output of that directory to our link verification script that should flag any issues with the links in the generated documentation.

[maorleger]

@weshaggard we do produce ref docs in PR builds 👍 do you think something like this would be feasible then?

Example: https://dev.azure.com/azure-sdk/public/_build/results?buildId=1322757&view=artifacts&pathAsName=false&type=publishedArtifacts where I pulled docs under packages -> {package-name} -> documentation

[weshaggard]

Yes I do think that is possible and worth a try. See https://github.com/Azure/azure-sdk-for-js/blob/main/eng/pipelines/templates/steps/analyze.yml#L38 where we verify the links of the MD files. We should be able to have a similar step that points to the ref docs output and runs across those files.

[ramya-rao-a]

@weshaggard In that case, should we move this to the azure-sdk-tools repo assuming this approach would apply to all languages?

[weshaggard]

I would expect that each language would need to plugin the step independently based on their doc generation process. From a central EngSys prospective I think all the pieces are available.

[ramya-rao-a]

Thanks @weshaggard

@JonathanCrd, Please work with @praveenkuttappan in the March milestone for this task

[JonathanCrd]

While checking en-us is good but I assume these will turn into real links in the ref docs so we should try and figure out a way to check that the links are valid.

@weshaggard are you suggesting to validate that the URLs work after checking that they don't contain the locale information?

I mean, check for 2 things: validity and locale?

[weshaggard]

Yes the work here is to run the verify-links script across all the generated html docs and that will verify that the links are both valid links and follow our guidelines like don't contain "en-us", etc.

[github-actions]

Hi @maorleger, we deeply appreciate your input into this project. Regrettably, this issue has remained inactive for over 2 years, leading us to the decision to close it. We've implemented this policy to maintain the relevance of our issue queue and facilitate easier navigation for new contributors. If you still believe this topic requires attention, please feel free to create a new issue, referencing this one. Thank you for your understanding and ongoing support.