CRDGenerator Development Doc(s)

baloo42 commented 2 months ago

Is your enhancement related to a problem? Please describe

I couldn't find any notes on previously made decissions regarding the CRDGenerator. I had to read a lot issues and code, which makes it a little bit hard to contribute.

Describe the solution you'd like

A Wiki page or DEVELOPMENT.md which describes architecture goals would be great.

Important details in issues

Content

Architecture Goals
Intended usage in upstream projects like Quarkus Operator SDK
CRDGenerator Architecture
Module Structure (api, apt, test...)
sundrio
Sort Algorithm for Decorators
Own Annotations vs Reusing existing Annotations
Roundtrips from CRD to java-code and back (with Java-Generator and CRDGenerator) are not supported at the moment. TBD: Is this a goal? --> no goal
Validation during generation
Logging during generation
Configuration for the generator (e.g. the flag for parallel-generation). TBD: Is this something we can consider for additional feature flags?

Additional User Documentation Content

Requirements (e.g. Java Version, specific JDKs)
FAQ / Recommendations

andreaTP commented 2 months ago

Hi @baloo42 and thanks for pointing this out. Regarding the CRD Generator I don't think we have much documentation other than the code itself at this point, maybe @metacosm knows something more.

I would be happy to support a new Development doc file sharing anything I know/is needed by answering direct questions. Meanwhile, please, go ahead with any additional questions you have and I'll provide as much context as I can 🙂

As a super general overview, the code has been mostly contributed by @iocanel and @metacosm , built on top of the sundrio project. The api module is designed to be utilized as a library in the Quarkus Operator Framework in the @BuildSteps. I have contributed some improvements to support the Keycloak Realm Import CRD. The rest comes mostly from bug fixes reported by the users.

baloo42 commented 2 months ago

Thanks, I would be happy to contribute at least the initial document once we have collected the most important content. I will update the list of contents in the description if there are more details incoming.

andreaTP commented 2 months ago

Own Annotations vs Reusing existing Annotations

We decided to go full down on using Own Annotations: we don't own the codebase of Jackson etc. and it becomes easily really complicated to try to match the original semantics with the needs of a generator.

Roundtrips

I would love to see a real-world use-case for this, as long as we don't have one it's a non-goal

manusa commented 2 months ago

Roundtrips

I would love to see a real-world use-case for this, as long as we don't have one it's a non-goal

+1 I'm really curious about your use case.

baloo42 commented 2 months ago

To bei clear: I don't know any use case for round tripping and I think it would be really hard to implement. I also think that's the reason why other similar "JsonSchema Generator" don't support it too. (I couldn't find a Tool which supports it).

But I have thought about it while reading the code of the fabric8 generators and it seems others have thought about it too (#5867).

That's why i have put it on the list... We should mention it, even if we declare it as a none-goal.

fabric8io / kubernetes-client