Establish home for v1.0.0 Go APIs

[joelanford]

Goals:

1. Eliminate current and prevent future side effects of dependency imports when importing APIs. (for example: see https://github.com/openshift/enhancements/blob/master/dev-guide/api-conventions.md#no-functions)
2. Put up barriers to breaking changes. Once we reach v1.0.0, we MUST avoid breaking changes.

Breaking changes include:

1. Anything that causes the go-apidiff job to fail. (see separate issues related to moving non-API Go code to an internal tree). The APIs will remain exported, so the go-apidiff job will ensure that our Go code defining the APIs is not breaking from a Go perspective.
2. Anything that would cause Kubernetes clients to experience a breaking change when interacting with instances of our CRD via the Kubernetes apiserver.

[joelanford]

To enshrine goal (1) in our codebase, we could implement a test that enforces a specific set of imports. Any future PR that wants to import a new import path would need to also modify our list of allowed import paths in our API.

I would anticipate that that list would start out as k8s.io/apimachinery.

Perhaps https://golangci-lint.run/usage/linters/#depguard would help.

[LalatenduMohanty]

As discussed in the community meeting we are changing this to an issue (from an epic) and will make it part of #1253

[camilamacedo86]

Hi @joelanford @LalatenduMohanty

We have the crd-diff and the go-apidiff
Also, we already combined all in a repo, so we still need this issue?
Has anything else more than we need to do here?

[acornett21]

I think dependent callers that need the API's will have trouble pulling in this mono-repo, IMO the API's should their own repo with as few deps as possible so they can be consumed easily and with low friction. That was another ask for this issue.

[camilamacedo86]

Hi @acornett21,

Thank you for your input! Just to clarify, are you suggesting decoupling the APIs from this repository and placing them in a separate project specifically for APIs?

If someone imports operator-framework/operator-controller, they will only get what is explicitly exposed—primarily the APIs. Any code that isn’t relevant to external users is kept within the internal/ directories. Given this, I don’t see a strong motivation to remove the APIs from this repo at this moment. I think we could closet this one ( if that is the go ) and wait until there’s a clear need to do so before making that decision

However, I might be missing something. Let me know if I’ve misunderstood your point!.

[acornett21]

Hi @camilamacedo86 Yes correct that is what I'm suggesting. And correct an importer does not have access to the /internal packages, but by forcing them to import the entire repo, this also forces them to import/take all of this projects dependencies, which is less then desirable and can cause conflicts for a consumer. If a caller needs k8's API's/CRD's they only use the API dependency which has minimal dependencies, same with OpenShift API.

The ask here would be what is similarly in place for OLMv0 with API repo

[LalatenduMohanty]

@acornett21 I was under an impression that mono repo would resolve this issue. But if it is not (as you mentioned in your comment) I would keep it separate from the monorepo epic.

[acornett21]

@LalatenduMohanty This issue isn't about the monorepo at all, it's about the API's, so my take is that it's already separate.