From d8be5ca7c30023f57f09afaad8604c33fd2eae84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Nicoll?= <stephane.nicoll@broadcom.com>
Date: Wed, 22 Oct 2025 13:33:26 +0200
Subject: [PATCH] Document properties that were added as deprecated

This commit handles a corner case where we have to add properties in
a release that represents something we mean to remove but that's not
ready to go away just yet.

Those properties are now considered in the changelog, but  marked as
deprecated.

Closes gh-47759
---
 .../configurationmetadata/changelog/Changelog.java    | 10 ++++++----
 .../changelog/ChangelogWriter.java                    | 11 ++++-------
 .../changelog/ChangelogTests.java                     |  7 ++++---
 .../src/test/resources/sample-2.0.json                | 10 ++++++++++
 .../src/test/resources/sample.adoc                    |  4 ++++
 5 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/main/java/org/springframework/boot/configurationmetadata/changelog/Changelog.java b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/main/java/org/springframework/boot/configurationmetadata/changelog/Changelog.java
index d6d2567277b..df46b7fb7e2 100644
--- a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/main/java/org/springframework/boot/configurationmetadata/changelog/Changelog.java
+++ b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/main/java/org/springframework/boot/configurationmetadata/changelog/Changelog.java
@@ -57,12 +57,14 @@ record Changelog(String oldVersionNumber, String newVersionNumber, List<Differen
 		}
 		for (ConfigurationMetadataProperty newProperty : newMetadata.getAllProperties().values()) {
 			if (!seenIds.contains(newProperty.getId())) {
-				if (newProperty.isDeprecated() && newProperty.getDeprecation().getLevel() == Level.ERROR) {
-					differences.add(new Difference(DifferenceType.DELETED, null, newProperty));
-				}
-				else if (!newProperty.isDeprecated()) {
+				if (!newProperty.isDeprecated()) {
 					differences.add(new Difference(DifferenceType.ADDED, null, newProperty));
 				}
+				else {
+					DifferenceType differenceType = (newProperty.getDeprecation().getLevel() == Level.ERROR)
+							? DifferenceType.DELETED : DifferenceType.ADDED;
+					differences.add(new Difference(differenceType, null, newProperty));
+				}
 			}
 		}
 		return List.copyOf(differences);
diff --git a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/main/java/org/springframework/boot/configurationmetadata/changelog/ChangelogWriter.java b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/main/java/org/springframework/boot/configurationmetadata/changelog/ChangelogWriter.java
index 3f56347a253..32db7488bdb 100644
--- a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/main/java/org/springframework/boot/configurationmetadata/changelog/ChangelogWriter.java
+++ b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/main/java/org/springframework/boot/configurationmetadata/changelog/ChangelogWriter.java
@@ -104,7 +104,10 @@ class ChangelogWriter implements AutoCloseable {
 	}
 
 	private void writeAdded(Difference difference) {
-		writeRegularPropertyRow(difference.newProperty());
+		ConfigurationMetadataProperty property = difference.newProperty();
+		writeCell(monospace(property.getId()) + (property.isDeprecated() ? " (deprecated)" : ""));
+		writeCell(monospace(asString(property.getDefaultValue())));
+		writeCell(property.getShortDescription());
 	}
 
 	private void writeRemoved(List<Difference> deleted, List<Difference> deprecated) {
@@ -157,12 +160,6 @@ class ChangelogWriter implements AutoCloseable {
 		write("|======================%n");
 	}
 
-	private void writeRegularPropertyRow(ConfigurationMetadataProperty property) {
-		writeCell(monospace(property.getId()));
-		writeCell(monospace(asString(property.getDefaultValue())));
-		writeCell(property.getShortDescription());
-	}
-
 	private void writeDeprecatedPropertyRow(ConfigurationMetadataProperty property) {
 		Deprecation deprecation = (property.getDeprecation() != null) ? property.getDeprecation() : new Deprecation();
 		writeCell(monospace(property.getId()));
diff --git a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/java/org/springframework/boot/configurationmetadata/changelog/ChangelogTests.java b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/java/org/springframework/boot/configurationmetadata/changelog/ChangelogTests.java
index bc99380388f..64c069a1fb6 100644
--- a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/java/org/springframework/boot/configurationmetadata/changelog/ChangelogTests.java
+++ b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/java/org/springframework/boot/configurationmetadata/changelog/ChangelogTests.java
@@ -39,13 +39,14 @@ class ChangelogTests {
 		assertThat(differences).isNotNull();
 		assertThat(differences.oldVersionNumber()).isEqualTo("1.0");
 		assertThat(differences.newVersionNumber()).isEqualTo("2.0");
-		assertThat(differences.differences()).hasSize(5);
+		assertThat(differences.differences()).hasSize(6);
 		List<Difference> added = differences.differences()
 			.stream()
 			.filter((difference) -> difference.type() == DifferenceType.ADDED)
 			.toList();
-		assertThat(added).hasSize(1);
-		assertProperty(added.get(0).newProperty(), "test.add", String.class, "new");
+		assertThat(added).hasSize(2)
+			.anySatisfy((entry) -> assertProperty(entry.newProperty(), "test.add", String.class, "new"))
+			.anySatisfy((entry) -> assertProperty(entry.newProperty(), "test.add.deprecated", String.class, "test2"));
 		List<Difference> deleted = differences.differences()
 			.stream()
 			.filter((difference) -> difference.type() == DifferenceType.DELETED)
diff --git a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/resources/sample-2.0.json b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/resources/sample-2.0.json
index 95a9b8ff501..61ac7058371 100644
--- a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/resources/sample-2.0.json
+++ b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/resources/sample-2.0.json
@@ -6,6 +6,16 @@
       "description": "Test add.",
       "defaultValue": "new"
     },
+    {
+      "name": "test.add.deprecated",
+      "type": "java.lang.String",
+      "description": "Test add deprecated.",
+      "defaultValue": "test2",
+      "deprecation": {
+        "replacement": "test.equal",
+        "reason": "Deprecated  in favor of Equal"
+      }
+    },
     {
       "name": "test.equal",
       "type": "java.lang.String",
diff --git a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/resources/sample.adoc b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/resources/sample.adoc
index fd4c354ad89..63b3e4b2c7e 100644
--- a/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/resources/sample.adoc
+++ b/configuration-metadata/spring-boot-configuration-metadata-changelog-generator/src/test/resources/sample.adoc
@@ -16,6 +16,10 @@ _None_.
 | `test.add`
 | `new`
 | Test add.
+
+| `test.add.deprecated` (deprecated)
+| `test2`
+| Test add deprecated.
 |======================