CRDGenerator Development Doc(s)

[baloo42]

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

• Generate a CRD with {type: string, format: date-time} #5867 (comment)
• fix(crd-generator): Fail if multiple versions are marked as stored #5846 (comment)
• Introduce specific annotations for the generators #4348
• Add support for Min, Max, Pattern and Nullable on CRD generator fields #4298
• Generate a CRD with {type: string, format: date-time} #5867 (comment)
• Support Conversion Hook Configuration in CRD Generation #4692 (comment)
• Add crd-generator and java-generator support for Format annotation #5885 (comment)
• CRD-Generator v7 - Orga #5942
• Use one resource annotation #4164

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]

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]

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]

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]

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]

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.