Update versions contained in README on maven release

Question

I'm maintaining an opensource project on github that contains README.md file with install instructions containing the current version of the project 1.0.0-SNAPSHOT.

When releasing a new version to maven central, is it possible to automatically update this version number contained in README.md ?

Releases are performed with maven-release-plugin, versions in pom.xml are well updated, but I can't find anything in the docs to update this external file properly.

Example:

README.md file currently at 1.0.0-SNAPSHOT. It lies outside of maven sources/resources, but it's managed on git. on mvn release:prepare, it should be updated to 1.0.0, and maven should then commit/push the change before tagging the new release. Then, on mvn release:perform it should go to the next development version 1.0.1-SNAPSHOT.

(Link to the project)

Answer 1

You can use the maven-resources-plugin for this like mentioned in the comments.

I didn't try it but the configuration should look something like this:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-resources-plugin</artifactId>
  <version>3.0.1</version>
  <executions>
    <execution>
      <id>readme-md</id>
      <phase>process-resources</phase>
      <goals>
        <goal>copy-resources</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.basedir}</outputDirectory>
        <resources>                                        
          <resource>
            <directory>${project.basedir}</directory>
            <includes>
              <include>README.md</include>
            </includes>
            <filtering>true</filtering>
          </resource>
        </resources>
        <encoding>UTF-8</encoding>
      </configuration>            
    </execution>
  </executions>
</plugin>

And in your README.md where you want the version you put the placeholder ${project.version}.

The two features which where combined here are copy-resources and filtering.

We tell the plugin to copy resources from the directory ${project.basedir}, which maven resolves to the root directory, again to the root directory but only include files matching README.md.

The filtering option replaces all placeholders with variables which can be defined as system properties, project properties, filter resources defined in the pom.xml or on command line. In this case we use the project property version.

Though the comments are right mentioning eventually inconsistency in case the release went wrong. You could overcome this by explicitly calling mvn resources:resources after your mvn release:perform was successful. I hope this helps.

Answer 2

You can try writing a bash script that builds your project and also modifies README.md file. Something like:

#!/bin/sh
VERSION=$1
mvn clean package
#modify the string manipulation command accordingly
sed -e "s/{VERSION}/${VERSION}/" ./README.md-tpl > ./README.md 

when running script, you can pass version number as first argument. You can use full path to your default README.md-tpl file.

Answer 3

Building onto Marvins answer,
you can keep your README.md in your usual place and include just a snippet of text.

The trick is that although Markdown does not allow to include text, it allows to include an svg-image and an svg-image can contain text that can be selected and copied in all browsers:

<svg xmlns="http://www.w3.org/2000/svg"
     xml:lang="en-GB" width="auto" height="7em">
    <style>
        svg {
            font-family: monospace;
            font-size: medium;
        }
    </style>

    <text x="0" y="1em">
        <tspan x="1em" dy="1em">&lt;dependency&gt;</tspan>
        <tspan x="3em" dy="1em">&lt;groupId&gt;${project.groupId}&lt;/groupId&gt;</tspan>
        <tspan x="3em" dy="1em">&lt;artifactId&gt;${project.artifactId}&lt;/artifactId&gt;</tspan>
        <tspan x="3em" dy="1em">&lt;version&gt;${project.version}&lt;/version&gt;</tspan>
        <tspan x="1em" dy="1em">&lt;/dependency&gt;</tspan>
    </text>
    
</svg>

This will render as:

<dependency>
  <groupId>${project.groupId}</groupId>
  <artifactId>${project.artifactId}</artifactId>
  <version>${project.version}</version>
</dependency>

(It will become a one-liner on paste, but that's okay. pom.xml are usually auto-formatted anyway)

You put that image into a directory called "templates" and a copy into a "docimages"-directory.

Now you can add your image to the README.md using a normal image-reference:
![mvn dependency](docimages/version.svg)
Note you're referencing the one in your "docimages" directory, not the one in your "templates" dir.

Now you just need a job in your pom.xml that copies and filters the image's source code:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-resources-plugin</artifactId>
  <version>3.0.1</version>
  <executions>
    <execution>
      <id>readme-md</id>
      <phase>process-resources</phase>
      <goals>
        <goal>copy-resources</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.basedir}/docimages</outputDirectory>
        <resources>                                        
          <resource>
            <directory>${project.basedir/templates}</directory>
            <includes>
              <include>version.svg</include>
            </includes>
            <filtering>true</filtering>
          </resource>
        </resources>
        <encoding>UTF-8</encoding>
      </configuration>            
    </execution>
  </executions>
</plugin>

"What's the benefit over filtering all of the readme?" You might ask.
Simple: A README.md can be large and can contain all kinds of variables as part of the documentation that you don't want to substitute. This will only substitute the variables in the SVG-file.

Answer 4

I have a combination of a few suggestions.

First, I substitued ${project.version} for the version in my README.md and moved it to the src/main/doc folder as Marvin suggested.

Then, I added an execution to the maven-resources-plugin in my build, like this:

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-resources-plugin</artifactId>
        <version>3.0.1</version>
        <executions>
            <execution>
                <id>readme</id>
                <phase>process-resources</phase>
                <goals>
                    <goal>copy-resources</goal>
                </goals>
                <configuration>
                    <outputDirectory>${project.basedir}</outputDirectory>
                    <resources>
                        <resource>
                            <directory>src/main/doc</directory>
                            <includes>
                                <include>README.md</include>
                            </includes>
                            <filtering>true</filtering>
                        </resource>
                    </resources>
                    <encoding>UTF-8</encoding>
                </configuration>
            </execution>
        </executions>
    </plugin>

Now, every time the plugin runs, it substitutes the project version in README.md and copies it to ${project.basedir}.

Finally, in the maven-release-plugin plugin, I added a few goals to run the above plugin, then add the newly updated README.md to the index before the commit:

   <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>3.0.0-M4</version>
        <configuration>
            <preparationGoals>resources:copy-resources@readme scm:add -Dincludes=README.md</preparationGoals>
            <completionGoals>resources:copy-resources@readme scm:add -Dincludes=README.md</completionGoals>
        </configuration>
    </plugin>

Now each time the release plugin commits the pom.xml, it will commit the README.md as well.