Move all CRD-related annotations (java-2-crd / crd-2-java) to a single package

[manusa]

Description

Ensure that all of the annotations on which the CRD-2-java and java-2-CRD modules rely on are on a single API package.

• crd-generator-api
• generator-annotations

[andreaTP]

@manusa thanks for filing this issue, there is a rationale behind the current split:

• shared annotations can be used by both crd-2-java and java-2-crd sub-modules
• java-2-crd annotations are usable exclusively by the java-2-crd generator since they do not make sense "the other way around"

More specifically:

• Annotations: are ignored by the crd-2-java generator
• Labels: are ignored by the crd-2-java generator
• PreserveUnknownFields: is performed automatically (or by configuration if this PR gets merged), in the crd-2-java is encoded using the additionalProperties field instead of an annotation
• PrinterColumn: is ignored by the crd-2-java generator
• SchemaFrom / SchemaSwap / SchemaSwaps: are tricks to artificially "patch" the class graph

[shawkins]

java-2-crd annotations are usable exclusively by the java-2-crd generator since they do not make sense "the other way around"

They can be in a different package, but they should both be in the generator-annotations module. If you don't know to scope crd-generator-api as provided, you'll end with extra stuff in your runtime classpath.

[andreaTP]

If you don't know to scope crd-generator-api as provided, you'll end with extra stuff in your runtime classpath.

The crd-generator is exclusively used at compile-time and should be marked as provided always, there is not much, other than documentation, we can do to prevent this kind of misuse.

The rationale behind the current separation is that:

• using the crd-generator it's already on the classpath and you have access to all of the annotations
• using the java-generator you only get the subset that you will effectively use

That said, if there is a general consensus to move everything to one sub-module I won't oppose it.
Reminder that we would need to roll this change in 2 minor release cycles:

1. deprecate the current annotations and introduce the new one
2. remove the deprecated annotations

[shawkins]

The crd-generator is exclusively used at compile-time and should be marked as provided always, there is not much, other than documentation, we can do to prevent this kind of misuse.

Documentation would be nice. But also consider the annotations are marked as runtime retention. In theory a user could expect to reflectively make decisions based upon them if they include the dependency at the compile scope - but again would need to exclude the unnecessary transitive dependencies.

Reminder that we would need to roll this change in 2 minor release cycles:

Only if they are repackaged. Just moving them to a different jar, that is likely already included in the classpath shouldn't be a problem.

[andreaTP]

Documentation would be nice. But also consider the annotations are marked as runtime retention. In theory a user could expect to reflectively make decisions based upon them if they include the dependency at the compile scope - but again would need to exclude the unnecessary transitive dependencies.

I'm not sure we really want this to happen anytime soon.

Only if they are repackaged. Just moving them to a different jar, that is likely already included in the classpath shouldn't be a problem.

Here I disagree, moving to a different artifact IS a breaking change, If there are no compelling reasons to rush this I strongly suggest going through the 2 cycles.

[shawkins]

Here I disagree, moving to a different artifact IS a breaking change,

Under what scenario would someone have a depedency, either provided or compile, on crd-generator-api and specifically exclude the generator-annoations transitive dependency? That seems quite unlikely.

If there are no compelling reasons to rush this I strongly suggest going through the 2 cycles.

That will require a repacking. Due to java module restrictions we don't want split packages.

[manusa]

We can discuss this internally on this week's sync meeting.