RFC: sig-architecture: document Go API guidelines

[pohly]

This documents (so far) informal best practices. The goal is to minimize the impact of accidental or intentional Go API changes on the wider ecosystem.

I intend to continue working on kubernetes/kubernetes#138351, then present both PRs in a SIG Architecture meeting. In the meantime, comments are welcome.

/cc @aojea @liggitt @dims @BenTheElder

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: pohly
Once this PR has been reviewed and has the lgtm label, please assign dims for approval. For more information see the Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• contributors/devel/sig-architecture/OWNERS

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

[BenTheElder]

First pass: Thank you and generally +1

I think surfacing this will be tricky, maybe we can, for example, emit a link alongside errors in any related presubmit tooling?

I'm also really wondering if we should shift to kubernetes.dev for docs like this, so it will be more readily search indexed, rendered, etc.

like https://www.kubernetes.dev/docs/code/cri-api-version-skew-policy/

[pohly]

maybe we can, for example, emit a link alongside errors in any related presubmit tooling?

Yes, absolutely.

I'm also really wondering if we should shift to kubernetes.dev for docs like this, so it will be more readily search indexed, rendered, etc.

Personally I don't care about rendering. I prefer simple Markdown over a more complex publishing pipeline. Right now I am not even sure where the source of kubernetes.dev is. Indexing in search engines might be relevant for some people.

I know that you asked about kubernetes.dev and as far as I remember, there was no conclusion what to do about it. Until there is, I prefer to keep this doc closer to https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api_changes.md. This makes it clear that this is the SIG Architecture guidance on this topic.

[pohly]

I know that you asked about kubernetes.dev and as far as I remember, there was no conclusion what to do about it.

Maybe as an interim, incremental solution we should more aggressively cross-reference https://github.com/kubernetes/community/contributors/devel from kubernetes.dev? That page current links to https://github.com/kubernetes/community/tree/main/contributors/devel on the start page under "developer" guides, but it's easy to miss and once a developer reaches https://www.kubernetes.dev/docs/ it's nowhere in sight.