Hi @squeed, as promised here is the small readme with some more high level bits that should explains how everything is tied together, let me know if that's what you had in mind 🙏.

Thanks for the review! 🙏

I'm personally not a big fan of this type of README files, as they tend to get stale over time given that no one ever remembers to update them subsequently. However, I don't actually see any better place for this type of information --- there's apparently no good location in the docs at the moment, and a doc.go file would suffer the same limitations (the only advantage is that it would be automatically used by godoc).

Yeah I agree, I am trying to be a bit high level here so that it hopefully decrease the chance of being out of date but this might still happen 😅.

Content wise, my main suggestion would be to reorganize a bit the content, as I feel that in the current form may be a bit difficult to understand without the full context. One possible idea could be:

* Adding a brief introductory paragraph with a bit more context, as simple as mentioning what MCS-API is and linking to the KEP;
* Having a bullet list (or a couple of paragraphs) about the core types, simply linking to the dedicated KEP sections when appropriate.

I tried explaining this in a small intro let me know if that's what you had in mind!

* Having a bullet list (or subsections) with one item for every controller (maybe mentioning in which file they are implemented?), briefly describing what they do, which are the inputs and outputs;

Hmm this is already sort of done in the paragraphs before the schema, it's not in a super structured way though. My intent was more to describe the general flow and the controllers involved rather than what each controllers individually does and there is also some documentation in the code about each controller as well.

* Briefly mentioning what conflict resolution is, and which role plays here -- again, just a simple sentence linking to the KEP, and possibly any additional info for non-trivial implementation choices where the KEP was not clear.

I added a small note about that, also hopefully the KEP is going to be updated with what was not clear about conflicts on the ServiceImport PR anyway.

/test

/ci-ginkgo