更新 Maven 版本的 README 中包含的版本

Question

我在 github 上维护一个开源项目，该项目包含 README.md 文件，安装说明包含项目的当前版本 1.0.0-SNAPSHOT。

发布新版本到maven central时，是否可以自动更新README.md中包含的这个版本号？

使用maven-release-plugin 执行发布，pom.xml 中的版本更新良好，但我在文档中找不到任何内容来正确更新此外部文件。

例子：

README.md 文件当前位于1.0.0-SNAPSHOT。它位于 Maven 源/资源之外，但它在 git 上进行管理。在mvn release:prepare 上，它应该更新为1.0.0，然后maven 应该在标记新版本之前提交/推送更改。然后，在mvn release:perform 上应该转到下一个开发版本1.0.1-SNAPSHOT。

(Link to the project)

Answer 1

您可以尝试编写一个 bash 脚本来构建您的项目并修改 README.md 文件。比如：

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

运行脚本时，您可以将版本号作为第一个参数传递。您可以使用默认 README.md-tpl 文件的完整路径。

Answer 2

您可以使用 maven-resources-plugin 来实现这一点，就像 cmets 中提到的那样。

我没试过，但配置应该是这样的：

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

并且在你想要的版本的 README.md 中放置占位符 ${project.version}。

这里结合的两个功能是copy-resources 和filtering。

我们告诉插件将资源从目录${project.basedir}（maven 解析到根目录）复制到根目录，但只包括与README.md 匹配的文件。

过滤选项将所有占位符替换为变量，这些变量可以定义为系统属性、项目属性、在 pom.xml 或命令行中定义的过滤器资源。在这种情况下，我们使用项目属性 version。

尽管 cmets 正确地提到了最终的不一致，以防发布出错。您可以通过在 mvn release:perform 成功后显式调用 mvn resources:resources 来克服这个问题。我希望这会有所帮助。

Answer 3

以马文斯的回答为基础，
您可以将 README.md 保存在您通常的位置，并且只包含一个 sn-p 文本。

诀窍在于，虽然 Markdown 不允许包含文本，但它允许包含 svg-image 并且 svg-image 可以包含可以在所有浏览器中选择和复制的文本：

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

这将呈现为：

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

（粘贴时会变成单行，但没关系。pom.xml 通常是自动格式化的）

您将该图像放入名为“templates”的目录中，并将副本放入“docimages”目录中。

现在您可以使用普通的图像参考将图像添加到 README.md：
![mvn dependency](docimages/version.svg)
请注意，您引用的是“docimages”目录中的那个，不是“模板”目录中的那个。

现在您只需要在 pom.xml 中复制和过滤图像源代码的作业：

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

“过滤所有自述文件有什么好处？”你可能会问。
简单：README.md 可以很大，并且可以包含各种变量作为您不想替换的文档的一部分。这只会替换 SVG 文件中的变量。

Answer 4

我有一些建议。

首先，我将 ${project.version} 替换为 README.md 中的版本，并按照 Marvin 的建议将其移至 src/main/doc 文件夹。

然后，我在构建中向maven-resources-plugin 添加了一个执行，如下所示：

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

现在，每次插件运行时，它都会替换 README.md 中的项目版本并将其复制到 ${project.basedir}。

最后，在maven-release-plugin插件中，我添加了几个目标来运行上面的插件，然后将新更新的README.md添加到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>

现在每次发布插件提交pom.xml，它也会提交README.md。