From 4f948dd482eaec60273696274401f2c275079cda Mon Sep 17 00:00:00 2001
From: Marcono1234 <Marcono1234@users.noreply.github.com>
Date: Tue, 25 Oct 2022 02:26:43 +0200
Subject: [PATCH] Automatically replace version references on `release:prepare`
 (#2212)

* Automatically replace version references on `release:prepare`

* Specify encoding and improve placeholder replacements

* Add `since $next-version$` for `JsonArray.asList` and `JsonObject.asMap`
---
 ReleaseProcess.md                             |  5 +-
 gson/src/main/java/com/google/gson/Gson.java  |  5 +-
 .../main/java/com/google/gson/JsonArray.java  |  1 +
 .../main/java/com/google/gson/JsonObject.java |  1 +
 pom.xml                                       | 72 +++++++++++++++++++
 5 files changed, 82 insertions(+), 2 deletions(-)

diff --git a/ReleaseProcess.md b/ReleaseProcess.md
index 6e2b923d..eaa0e7c5 100644
--- a/ReleaseProcess.md
+++ b/ReleaseProcess.md
@@ -6,7 +6,6 @@ The following is a step-by-step procedure for releasing a new version of Google-
 1. Ensure all changelists are code-reviewed and have +1
 1. `cd gson` to the parent directory; ensure there are no open files and all changes are committed.
 1. Run `mvn release:clean`
-1. Do a dry run: `mvn release:prepare -DdryRun=true`
 1. Start the release: `mvn release:prepare`
     - Answer questions: usually the defaults are fine. Try to follow [Semantic Versioning](https://semver.org/) when choosing the release version number.
     - This will do a full build, change version from `-SNAPSHOT` to the released version, commit and create the tags. It will then change the version to `-SNAPSHOT` for the next release.
@@ -18,9 +17,13 @@ The following is a step-by-step procedure for releasing a new version of Google-
 1. Update version references in (version might be referenced multiple times):
     - [`README.md`](README.md)
     - [`UserGuide.md`](UserGuide.md)
+
+    Note: When using the Maven Release Plugin as described above, these version references should have been replaced automatically, but verify this manually nonetheless to be on the safe side.
 1. Optional: Create a post on the [Gson Discussion Forum](https://groups.google.com/group/google-gson).
 1. Optional: Update the release version in [Wikipedia](https://en.wikipedia.org/wiki/Gson) and update the current "stable" release.
 
+Important: When aborting a release / rolling back release preparations, make sure to also revert all changes to files which were done during the release (e.g. automatic replacement of version references).
+
 ## Configuring a machine for deployment to Sonatype Repository
 
 This section was borrowed heavily from [Doclava release process](https://code.google.com/archive/p/doclava/wikis/ProcessRelease.wiki).
diff --git a/gson/src/main/java/com/google/gson/Gson.java b/gson/src/main/java/com/google/gson/Gson.java
index 22071a17..7e0cce21 100644
--- a/gson/src/main/java/com/google/gson/Gson.java
+++ b/gson/src/main/java/com/google/gson/Gson.java
@@ -1024,6 +1024,7 @@ public final class Gson {
    *
    * @see #fromJson(Reader, TypeToken)
    * @see #fromJson(String, Class)
+   * @since $next-version$
    */
   public <T> T fromJson(String json, TypeToken<T> typeOfT) throws JsonSyntaxException {
     if (json == null) {
@@ -1116,6 +1117,7 @@ public final class Gson {
    *
    * @see #fromJson(String, TypeToken)
    * @see #fromJson(Reader, Class)
+   * @since $next-version$
    */
   public <T> T fromJson(Reader json, TypeToken<T> typeOfT) throws JsonIOException, JsonSyntaxException {
     JsonReader jsonReader = newJsonReader(json);
@@ -1199,6 +1201,7 @@ public final class Gson {
    *
    * @see #fromJson(Reader, TypeToken)
    * @see #fromJson(JsonReader, Type)
+   * @since $next-version$
    */
   public <T> T fromJson(JsonReader reader, TypeToken<T> typeOfT) throws JsonIOException, JsonSyntaxException {
     boolean isEmpty = true;
@@ -1304,10 +1307,10 @@ public final class Gson {
    * @return an object of type T from the JSON. Returns {@code null} if {@code json} is {@code null}
    * or if {@code json} is empty.
    * @throws JsonSyntaxException if json is not a valid representation for an object of type typeOfT
-   * @since 1.3
    *
    * @see #fromJson(Reader, TypeToken)
    * @see #fromJson(JsonElement, Class)
+   * @since $next-version$
    */
   public <T> T fromJson(JsonElement json, TypeToken<T> typeOfT) throws JsonSyntaxException {
     if (json == null) {
diff --git a/gson/src/main/java/com/google/gson/JsonArray.java b/gson/src/main/java/com/google/gson/JsonArray.java
index e9ce580c..fadc7664 100644
--- a/gson/src/main/java/com/google/gson/JsonArray.java
+++ b/gson/src/main/java/com/google/gson/JsonArray.java
@@ -406,6 +406,7 @@ public final class JsonArray extends JsonElement implements Iterable<JsonElement
    * Use {@link JsonNull} for JSON null values.
    *
    * @return mutable {@code List} view
+   * @since $next-version$
    */
   public List<JsonElement> asList() {
     return new NonNullElementWrapperList<>(elements);
diff --git a/gson/src/main/java/com/google/gson/JsonObject.java b/gson/src/main/java/com/google/gson/JsonObject.java
index 0c36ef24..d1c6b30b 100644
--- a/gson/src/main/java/com/google/gson/JsonObject.java
+++ b/gson/src/main/java/com/google/gson/JsonObject.java
@@ -220,6 +220,7 @@ public final class JsonObject extends JsonElement {
    * Use {@link JsonNull} for JSON null values.
    *
    * @return mutable {@code Map} view
+   * @since $next-version$
    */
   public Map<String, JsonElement> asMap() {
     // It is safe to expose the underlying map because it disallows null keys and values
diff --git a/pom.xml b/pom.xml
index b7327676..140ab0d3 100644
--- a/pom.xml
+++ b/pom.xml
@@ -136,8 +136,80 @@
             <!-- Disable Maven Super POM release profile and instead use own one -->
             <useReleaseProfile>false</useReleaseProfile>
             <releaseProfiles>release</releaseProfiles>
+            <!-- Run custom goals to replace version references, see plugin configuration below -->
+            <!-- Also run `package`; otherwise goals fail for modules depending on each; possibly
+              same issue as https://issues.apache.org/jira/browse/MRELEASE-271 -->
+            <preparationGoals>
+              package -DskipTests
+              antrun:run@replace-version-placeholders
+              antrun:run@replace-old-version-references
+              antrun:run@git-add-changed
+            </preparationGoals>
           </configuration>
         </plugin>
+        <plugin>
+          <artifactId>maven-antrun-plugin</artifactId>
+          <version>3.1.0</version>
+          <executions>
+            <!-- Replaces version placeholders with the current version; this is mainly useful for
+              Javadoc where this allows writing `@since $next-version$` -->
+            <execution>
+              <id>replace-version-placeholders</id>
+              <goals>
+                <goal>run</goal>
+              </goals>
+              <configuration>
+                <target>
+                  <replace token="$next-version$" value="${project.version}" encoding="${project.build.sourceEncoding}">
+                    <!-- erroronmissingdir=false for gson-parent which does not have source directory -->
+                    <fileset dir="${project.build.sourceDirectory}" includes="**" erroronmissingdir="false" />
+                  </replace>
+                </target>
+              </configuration>
+            </execution>
+            <!-- Replaces references to the old version in the documentation -->
+            <execution>
+              <id>replace-old-version-references</id>
+              <goals>
+                <goal>run</goal>
+              </goals>
+              <configuration>
+                <target>
+                  <!-- Replace Maven and Gradle version references; uses regex lookbehind and lookahead -->
+                  <replaceregexp match="(?&lt;=&lt;version&gt;).*(?=&lt;/version&gt;)|(?&lt;='com\.google\.code\.gson:gson:).*(?=')" flags="g" replace="${project.version}" encoding="${project.build.sourceEncoding}">
+                    <fileset dir="${project.basedir}">
+                      <include name="README.md" />
+                      <include name="UserGuide.md" />
+                    </fileset>
+                  </replaceregexp>
+                </target>
+              </configuration>
+              <!-- Only has to be executed for parent project; don't inherit this to modules -->
+              <!-- This might be a bit hacky; execution with this ID seems to be missing for modules and Maven just executes default
+                configuration which does not have any targets configured. (not sure if this behavior is guaranteed) -->
+              <inherited>false</inherited>
+            </execution>
+            <!-- Adds changed files to the Git index; workaround because Maven Release Plugin does not support committing
+              additional files yet (https://issues.apache.org/jira/browse/MRELEASE-798), and for workarounds with
+              Maven SCM Plugin it is apparently necessary to know modified files in advance -->
+            <!-- Maven Release Plugin then just happens to include these changed files in its Git commit;
+              not sure if this behavior is guaranteed or if this relies on implementation details -->
+            <execution>
+              <id>git-add-changed</id>
+              <goals>
+                <goal>run</goal>
+              </goals>
+              <configuration>
+                <target>
+                  <exec executable="git" dir="${project.basedir}" failonerror="true">
+                    <arg value="add" />
+                    <arg value="." />
+                  </exec>
+                </target>
+              </configuration>
+            </execution>
+          </executions>
+        </plugin>
         <!-- Plugin for checking source and binary compatibility; used by GitHub workflow -->
         <plugin>
           <groupId>com.github.siom79.japicmp</groupId>