From 95013d3a70c191bc73e61d9854046cbadcdc6af8 Mon Sep 17 00:00:00 2001
From: Guillaume Smet <guillaume.smet@gmail.com>
Date: Wed, 8 Jan 2025 14:53:11 +0100
Subject: [PATCH] Add javadoc for ReleaseInformation

---
 .../bot/release/ReleaseInformation.java       | 54 ++++++++++++++++++-
 1 file changed, 52 insertions(+), 2 deletions(-)

diff --git a/src/main/java/io/quarkus/bot/release/ReleaseInformation.java b/src/main/java/io/quarkus/bot/release/ReleaseInformation.java
index 9afd764..19ebb4d 100644
--- a/src/main/java/io/quarkus/bot/release/ReleaseInformation.java
+++ b/src/main/java/io/quarkus/bot/release/ReleaseInformation.java
@@ -20,7 +20,8 @@ public class ReleaseInformation {
     private boolean maintenance;
 
     @JsonCreator
-    public ReleaseInformation(String version, String branch, String originBranch, String qualifier, boolean major, boolean firstFinal, boolean maintenance) {
+    public ReleaseInformation(String version, String branch, String originBranch, String qualifier, boolean major,
+            boolean firstFinal, boolean maintenance) {
         this.version = version;
         this.branch = branch;
         this.originBranch = originBranch;
@@ -34,6 +35,9 @@ public String getVersion() {
         return version;
     }
 
+    /**
+     * @return the version appended with " LTS" if this is an LTS release, the version otherwise
+     */
     @JsonIgnore
     public String getFullVersion() {
         if (Branches.isLts(branch)) {
@@ -47,6 +51,9 @@ public String getBranch() {
         return branch;
     }
 
+    /**
+     * @return the branch appended with " LTS" if this is an LTS release, the branch otherwise
+     */
     @JsonIgnore
     public String getFullBranch() {
         if (Branches.isLts(branch)) {
@@ -56,14 +63,28 @@ public String getFullBranch() {
         return branch;
     }
 
+    /**
+     * @return the branch from which we branch the CR1 release - it is main except when preparing the CR1 of an LTS release, in
+     *         which case it is the previous version branch as we want to branch CR1 from the previous version branch. For any
+     *         other release than the CR1, this is not consumed.
+     */
     public String getOriginBranch() {
         return originBranch;
     }
 
+    /**
+     * @return the qualifier (Alpha1, CR1, CR2...). Will be {@code null} for final releases. See {@link #isFinal()}.
+     */
     public String getQualifier() {
         return qualifier;
     }
 
+    /**
+     * @return whether it's a maintenance release, meaning this release is for a branch that is older than the latest
+     *         branch for which we have a final release.
+     *         For instance, if the latest branch for which we have a final release is 3.17 (we released 3.17.0 Platform), 3.16
+     *         is considered a maintenance branch, together will all previous branches).
+     */
     public boolean isMaintenance() {
         return maintenance;
     }
@@ -79,20 +100,34 @@ public boolean isComplete() {
         return version != null;
     }
 
+    /**
+     * @return whether this version is the first final of a given branch, it will be .0 in most cases but can be .1 if we didn't
+     *         release the .0 Platform (which happens when we find a critical bug in the core release between the initial .0
+     *         release and the full Platform release)
+     */
     public boolean isFirstFinal() {
         return firstFinal;
     }
 
+    /**
+     * @return whether this version is a final release (e.g. not an alpha or a CR)
+     */
     @JsonIgnore
     public boolean isFinal() {
         return qualifier == null || qualifier.isBlank() || qualifier.equals("Final");
     }
 
+    /**
+     * @return whether this version is a candidate release
+     */
     @JsonIgnore
     public boolean isCR() {
         return qualifier != null && qualifier.startsWith("CR");
     }
 
+    /**
+     * @return whether this version is the .0. Be careful, it doesn't mean it's the first final (see {@link #isFirstFinal()}).
+     */
     @JsonIgnore
     public boolean isDot0() {
         if (version == null) {
@@ -102,24 +137,39 @@ public boolean isDot0() {
         return Versions.isDot0(version);
     }
 
+    /**
+     * @return whether this version is the CR1
+     */
     @JsonIgnore
     public boolean isFirstCR() {
         return "CR1".equalsIgnoreCase(qualifier);
     }
 
+    /**
+     * @return whether this is a major new release (e.g. 4.0.0.CR1)
+     */
     public boolean isMajor() {
         return major;
     }
 
+    /**
+     * @return whether the origin branch for creating the branch is the main branch (see {@link #getOriginBranch()} for more
+     *         details)
+     */
     @JsonIgnore
     public boolean isOriginBranchMain() {
         return Branches.MAIN.equals(originBranch);
     }
 
+    /**
+     * @return whether this version is an LTS maintenance release with the regular release cadence (so a release from a LTS
+     *         branch, not a first final, and post 3.15 included)
+     */
     @JsonIgnore
     public boolean isLtsMaintenanceReleaseWithRegularReleaseCadence() {
         if (version == null) {
-            throw new IllegalStateException("Unable to know if the version is a LTS maintenance release with regular release cadence at this stage");
+            throw new IllegalStateException(
+                    "Unable to know if the version is a LTS maintenance release with regular release cadence at this stage");
         }
 
         return Branches.isLtsBranchWithRegularReleaseCadence(branch) && isFinal() && !isFirstFinal();