Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/website: add regression tests HTML anchors of important docs don't change #61499

Open
dolmen opened this issue Jul 21, 2023 · 6 comments
Open
Labels
Documentation help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. website

Comments

@dolmen
Copy link
Contributor

dolmen commented Jul 21, 2023

Previously the documentation for go doc links was at: https://go.dev/doc/comment#doc-links
Now it is at: https://go.dev/doc/comment#doclinks
The difference is in the hashref.

As now both links are in use (probably mostly by myself as I am a big promoter of godoc links), a redirect would be helpful.

@heschi
Copy link
Contributor

heschi commented Jul 21, 2023

cc @golang/tools-team

@heschi heschi added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jul 21, 2023
@heschi heschi added this to the Unreleased milestone Jul 21, 2023
@seankhliao seankhliao changed the title doc: add redirect for old URL of godoc links documentation x/website: add redirect for old URL of godoc links documentation Jul 21, 2023
@zigo101
Copy link

zigo101 commented Jul 22, 2023

Hashrefs in urls are not visible for servers. So the solution should be to add both IDs (doc-links and doclinks) for the target.

@hyangah
Copy link
Contributor

hyangah commented Jul 26, 2023

@dolmen Can you help us find where doc-links hashref is used?

@dolmen
Copy link
Contributor Author

dolmen commented Jul 26, 2023

I have used the hash ref in GitHub issues, PRs, Slack to tell people about godoc links.

@hyangah
Copy link
Contributor

hyangah commented Jul 26, 2023

@dolmen I fully understand how frustrating it is when old links no longer work. But I want to understand is what prevents from starting to use the new #doclinks. Is it to make the historical comments in old github issues, prs, and slack conversation valid?

The source of this link is in https://github.com/golang/website/blob/5c08bf3ee65177ad7160bd55d4a04bc613d6af9b/_content/doc/comment.md?plain=1#L610

As shown, this is a simplified markdown file, which the server processes and renders to a html file. We cannot remove doclinks which will break other users. I am not sure what to associate the extra hashref with.

@hyangah hyangah added the WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided. label Jul 26, 2023
@dolmen
Copy link
Contributor Author

dolmen commented Aug 20, 2023

If #doclinks is guaranteed to be stable from now, that's enough for my future use cases.

As the anchor seems to be defined in the document (and not by an algorithm) I expect that future breaking changes will be caught by code review. However a regression test on HTML anchors would be useful. Maybe this already somewhat exists if a test checks that links in the whole Go documentation are correctly resolved down to hashrefs.

@hyangah hyangah removed the WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided. label Aug 31, 2023
@hyangah hyangah changed the title x/website: add redirect for old URL of godoc links documentation x/website: add regression tests HTML anchors of important docs don't change Aug 31, 2023
@hyangah hyangah modified the milestones: Unreleased, website/unplanned Aug 31, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. website
Projects
None yet
Development

No branches or pull requests

5 participants