Add new CRD annotation to indicate Strimzi version when a property wa…

…s added (#9515)

Signed-off-by: Jakub Scholz <www@scholzj.com>

api/src/main/java/io/strimzi/api/kafka/model/KafkaClusterSpec.java

@@ -11,6 +11,7 @@
 import io.strimzi.api.kafka.model.listener.arraylistener.GenericKafkaListener;
 import io.strimzi.api.kafka.model.storage.Storage;
 import io.strimzi.api.kafka.model.template.KafkaClusterTemplate;
+import io.strimzi.crdgenerator.annotations.AddedIn;
 import io.strimzi.crdgenerator.annotations.Description;
 import io.strimzi.crdgenerator.annotations.DescriptionFile;
 import io.strimzi.crdgenerator.annotations.KubeLink;
@@ -84,6 +85,7 @@ public void setVersion(String version) {
         this.version = version;
     }
 
+    @AddedIn("0.39.0")
     @Description("The KRaft metadata version used by the Kafka cluster. " +
             "This property is ignored when running in ZooKeeper mode. " +
             "If the property is not set, it defaults to the metadata version that corresponds to the `version` property.")

api/src/main/java/io/strimzi/api/kafka/model/nodepool/KafkaNodePoolStatus.java

@@ -8,6 +8,7 @@
 import com.fasterxml.jackson.annotation.JsonPropertyOrder;
 import io.strimzi.api.kafka.model.Constants;
 import io.strimzi.api.kafka.model.status.Status;
+import io.strimzi.crdgenerator.annotations.AddedIn;
 import io.strimzi.crdgenerator.annotations.Description;
 import io.sundr.builder.annotations.Buildable;
 import lombok.EqualsAndHashCode;
@@ -55,6 +56,7 @@ public void setClusterId(String clusterId) {
         this.clusterId = clusterId;
     }
 
+    @AddedIn("0.39.0")
     @Description("The roles currently assigned to this pool.")
     public List<ProcessRoles> getRoles() {
         return roles;

crd-generator/src/main/java/io/strimzi/crdgenerator/DocGenerator.java

@@ -9,6 +9,7 @@
 import io.strimzi.api.annotations.ApiVersion;
 import io.strimzi.api.annotations.DeprecatedProperty;
 import io.strimzi.api.annotations.DeprecatedType;
+import io.strimzi.crdgenerator.annotations.AddedIn;
 import io.strimzi.crdgenerator.annotations.Crd;
 import io.strimzi.crdgenerator.annotations.Description;
 import io.strimzi.crdgenerator.annotations.DescriptionFile;
@@ -173,6 +174,9 @@ private void appendCommonTypeDoc(Crd crd, Class<?> cls) throws IOException {
             String externalUrl = linker != null && kubeLink != null ? linker.link(kubeLink) : null;
             addExternalUrl(property, kubeLink, externalUrl);
 
+            // Add the version the field was added in
+            addAddedIn(property);
+
             // Add the types to the `types` array to also generate the docs for the type itself
             Class<?> documentedType = propertyType.isArray() ? propertyType.arrayBase() : propertyType.getType();
 
@@ -235,6 +239,21 @@ private void addDescription(Class<?> cls, Property property) throws IOException
         }
     }
 
+    /**
+     * Sets the version in which the property was added. It is done only for properties that have the AddedIn annotation.
+     *
+     * @param property  The property for which the version should be added
+     *
+     * @throws IOException  Throws IOException when appending to the output fails
+     */
+    private void addAddedIn(Property property) throws IOException {
+        AddedIn addedIn = property.getAnnotation(AddedIn.class);
+
+        if (addedIn != null) {
+            out.append(" Added in Strimzi " + addedIn.value() + ".");
+        }
+    }
+
     /**
      * Sets the external link to Kubernetes docs or the link for fields distinguished by `type`
      *

crd-generator/src/main/java/io/strimzi/crdgenerator/annotations/AddedIn.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright Strimzi authors.
+ * License: Apache License 2.0 (see the file LICENSE or http://apache.org/licenses/LICENSE-2.0.html).
+ */
+package io.strimzi.crdgenerator.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks the Strimzi version in which given field was added
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.METHOD, ElementType.FIELD})
+public @interface AddedIn {
+    /**
+     * @return  Strimzi version in which the API field was added
+     */
+    String value();
+}

crd-generator/src/test/java/io/strimzi/crdgenerator/ExampleCrd.java

@@ -11,6 +11,7 @@
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
 import io.fabric8.kubernetes.api.model.Affinity;
 import io.fabric8.kubernetes.client.CustomResource;
+import io.strimzi.crdgenerator.annotations.AddedIn;
 import io.strimzi.crdgenerator.annotations.Crd;
 import io.strimzi.crdgenerator.annotations.Description;
 import io.strimzi.crdgenerator.annotations.Example;
@@ -245,6 +246,7 @@ public void setString(String string) {
     @Description("An example int property")
     @Example("42")
     @Minimum(42)
+    @AddedIn("0.0.1")
     public int getIntProperty() {
         return intProperty;
     }

crd-generator/src/test/resources/io/strimzi/crdgenerator/simpleTest.adoc

@@ -31,7 +31,7 @@
 |string
 |fieldProperty           1.2+<.<a|Example of field property.
 |string
-|intProperty             1.2+<.<a|An example int property.
+|intProperty             1.2+<.<a|An example int property. Added in Strimzi 0.0.1.
 |integer
 |listOfArray             1.2+<.<a|
 |string array of dimension 2

documentation/modules/appendix_crds.adoc

@@ -61,7 +61,7 @@ include::../api/io.strimzi.api.kafka.model.KafkaClusterSpec.adoc[leveloffset=+1]
 |Property                    |Description
 |version              1.2+<.<a|The Kafka broker version. Defaults to the latest version. Consult the user documentation to understand the process required to upgrade or downgrade the version.
 |string
-|metadataVersion      1.2+<.<a|The KRaft metadata version used by the Kafka cluster. This property is ignored when running in ZooKeeper mode. If the property is not set, it defaults to the metadata version that corresponds to the `version` property.
+|metadataVersion      1.2+<.<a|The KRaft metadata version used by the Kafka cluster. This property is ignored when running in ZooKeeper mode. If the property is not set, it defaults to the metadata version that corresponds to the `version` property. Added in Strimzi 0.39.0.
 |string
 |replicas             1.2+<.<a|The number of pods in the cluster.
 |integer
@@ -3501,7 +3501,7 @@ Used in: xref:type-KafkaNodePool-{context}[`KafkaNodePool`]
 |integer array
 |clusterId           1.2+<.<a|Kafka cluster ID.
 |string
-|roles               1.2+<.<a|The roles currently assigned to this pool.
+|roles               1.2+<.<a|The roles currently assigned to this pool. Added in Strimzi 0.39.0.
 |string (one or more of [controller, broker]) array
 |replicas            1.2+<.<a|The current number of pods being used to provide this resource.
 |integer