Automatically replace version references on release:prepare

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).

gson/src/main/java/com/google/gson/Gson.java

@@ -1019,6 +1019,7 @@ public <T> T fromJson(String json, Type typeOfT) throws JsonSyntaxException {
    *
    * @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) {
@@ -1111,6 +1112,7 @@ public <T> T fromJson(Reader json, Type typeOfT) throws JsonIOException, JsonSyn
    *
    * @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);
@@ -1194,6 +1196,7 @@ public <T> T fromJson(JsonReader reader, Type typeOfT) throws JsonIOException, J
    *
    * @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;
@@ -1299,10 +1302,10 @@ public <T> T fromJson(JsonElement json, Type typeOfT) throws JsonSyntaxException
    * @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) {

pom.xml

@@ -136,8 +136,75 @@
             <!-- 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>
+                <!-- Don't fail because for gson-parent the source directory does not exist; will still print
+                  exception with stack trace on console, but won't fail the build -->
+                <failOnError>false</failOnError>
+                <target>
+                  <replace dir="${project.build.sourceDirectory}" token="$next-version$" value="${project.version}" />
+                </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}">
+                  <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 change 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>