k8s.io: Redirect common Go package URLs to pkg.go.dev

[imjasonh]

Today, a valid Go import path like k8s.io/api/core/v1 redirects to https://kubernetes.io/api/core/v1 when viewed in a browser, which is an unhelpful 404. 😢

With this change, I'd like to propose that that import path should redirect to the much more helpful Go package documentation at https://pkg.go.dev/k8s.io/api/core/v1

This change currently only applies to:

• k8s.io/api/...
• k8s.io/apimachinery/...
• k8s.io/client-go/...
• k8s.io/kubernetes/...

If this is helpful we can look into applying this across more repos. The Go import redirects triggered by the presence of ?go-get=1 should be unaffected.

[linux-foundation-easycla]

The committers are authorized under a signed CLA.

• ✅ Jason Hall (ff2e2ae)

[k8s-ci-robot]

Welcome @imjasonh!

It looks like this is your first PR to kubernetes/k8s.io 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/k8s.io has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @imjasonh. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[ameukam]

/assign @spiffxp
cc @thockin

[cblecker]

/ok-to-test
/hold

@imjasonh Thanks for opening this! I could see this being helpful. However I'd want to chat with the sig-docs team that is responsible for the website first if they have any concerns.

@kubernetes/sig-docs-en-owners Hello! This change is to potentially move redirect some URLs that correspond to git packages to the pkg.go.dev.. these URLs would currently go to the website, but as there is unlikely to be content that directly matches the go package URL. Do you have any thoughts?

@liggitt @thockin @nikhita Also wanted to ping the three of you on this.. with the way we publish these packages, are the pkg.go.dev docs the right place to potentially redirect to? I know I've seen some funkiness before with these docs if you have irregular go module tagging practice.

[liggitt]

@liggitt @thockin @nikhita Also wanted to ping the three of you on this.. with the way we publish these packages, are the pkg.go.dev docs the right place to potentially redirect to? I know I've seen some funkiness before with these docs if you have irregular go module tagging practice.

no concerns from my side - https://pkg.go.dev/k8s.io/client-go was the weirdest one and that got cleaned up by kubernetes/kubernetes#98267 and golang/go#43265

[imjasonh]

@imjasonh Thanks for opening this! I could see this being helpful. However I'd want to chat with the sig-docs team that is responsible for the website first if they have any concerns.

No problem! Definitely makes sense to check with anybody and everybody who might see where this can unexpected go wrong.

@kubernetes/sig-docs-en-owners Hello! This change is to potentially move redirect some URLs that correspond to git packages to the pkg.go.dev.. these URLs would currently go to the website, but as there is unlikely to be content that directly matches the go package URL. Do you have any thoughts?

I actually found that https://k8s.io/kubernetes redirects to https://kubernetes.io/docs/home/ today, so we should probably not change this in case something depends on it.

Ideally I'd like to put in redirects for all the packages in https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io since these tend to be Go packages with useful godoc. But api, apimachinery and client-go are the ones I most often find myself wanting, and I didn't want to jump straight to generating the list (somehow...), so I'm fine starting with those three and seeing how it lands before proceeding with more.

I'd also be interested in feedback about how to make this sort of change easier to test before merging and rolling it out. The test.py seems to only test current prod URLs (unless I'm missing something), which makes it a bit scary to propose changes.

[sftim]

If we make this change, are we setting a convention that could set us up for a future collision with the website and its short URLs?

[sftim]

I think I'd implement this kind of redirect by editing https://github.com/kubernetes/website/blob/main/static/_redirects

Would that work? It's more visible and less likely to conflict with SIG Docs changes / plans.

[imjasonh]

Ooh, nice. I didn't know that was also an option, this definitely seems like an easier place to put these, with preview deploys and tests and everything. I'll look into it, and possibly close this PR. 👍

[cblecker]

Yeah, I think this might be the better overall path as then we are saying: "unless we know for sure they are trying to do a go get, then it should go to the website, and then sig-docs can do things there". Especially if this is a manual list.

[imjasonh]

If we make this change, are we setting a convention that could set us up for a future collision with the website and its short URLs?

Good question.

As an example, k8s.io/community currently redirects to (valid, useful) https://kubernetes.io/community, even though it's also a valid Go module with godoc: https://pkg.go.dev/k8s.io/community -- I definitely think we should prefer the existing redirect instead of redirecting to potentially-useful-but-probably-less-so godoc pages.

This seems to me like more signal that we should maintain a hand-edited list instead of trying too hard to automate it. If we do automate it, we should have a list of exceptions for things like community and any others we find or invent in the future.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: imjasonh
To complete the pull request process, please ask for approval from spiffxp after the PR has been reviewed.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• apps/k8s-io/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[imjasonh]

Closing this in favor of kubernetes/website#30692

Thanks for you feedback everyone! 🙏