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

您可以像评论中提到的那样使用maven-resources-plugin。

我没有尝试过，但配置看起来应该是这样的：

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

虽然这些评论在发布错误的情况下正确地提到了最终的不一致。您可以在mvn resources:resources成功后显式调用mvn release:perform来解决此问题。我希望这会有所帮助。

Answer 2

以马文斯的回答为基础，
你可以把你的 README.md 放在你平常的地方，只包含一段文本。

诀窍在于，虽然 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”目录中的那个，不是“templates”目录中的那个。

现在你只需要在你的 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 3

您可以尝试编写构建项目的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 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添加到提交前的索引中：

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

在maven版本上更新README中包含的版本

4 个答案: