dotnet / runtime

.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.
https://docs.microsoft.com/dotnet/core/
MIT License
15.06k stars 4.69k forks source link

Normalize links in Markdown files #101550

Open kimsey0 opened 5 months ago

kimsey0 commented 5 months ago

Issue

The runtime repository contains a lot of Markdown files with internal links to other files in the repository. Most of these use paths that are relative to either the root of the repository:

https://github.com/dotnet/runtime/blob/3f30cb9c9b392d127c0e4fbea2333dd1e6b82803/CONTRIBUTING.md?plain=1#L66

or to the file itself:

https://github.com/dotnet/runtime/blob/3f30cb9c9b392d127c0e4fbea2333dd1e6b82803/docs/README.md?plain=1#L74

However, some use GitHub URLs instead;

https://github.com/dotnet/runtime/blob/3f30cb9c9b392d127c0e4fbea2333dd1e6b82803/docs/project/breaking-change-process.md?plain=1#L48

When viewing the Markdown files on GitHub, this makes little difference, since GitHub automatically resolves any relative paths. However, when viewing the files locally, for example in Visual Studio Code, these GitHub links open in a browser instead of in the local editor.

Suggestion

Could we change all these GitHub URLs into paths relative to the root instead? I'm happy to create a pull request.

Additional information

There are also some links to file versions in specific commits. Most of these link to specific sections or lines that could be renamed or moved in the future, and should therefore likely be left alone.

Changing to relative paths will affect any future repository renames and merges (positively, keeping the links valid) plus splits (positively, for links between files that are moved out, and negatively, for links back to the original repository). I don't think this should be a big consideration.

I do not think this change affects any efforts to validate links in #38631.

dotnet-policy-service[bot] commented 5 months ago

Tagging subscribers to this area: @dotnet/area-meta See info in area-owners.md if you want to be subscribed.

eiriktsarpalis commented 2 months ago

@kimsey0 feel free to submit a PR improving things.