Semantic Versioning 技术文档

1. 安装指南

1.1 通过 Maven 安装

要在 Maven 项目中使用 semantic-versioning，首先需要在 pom.xml 文件中添加依赖：

<dependency>
    <groupId>org.semver</groupId>
    <artifactId>enforcer-rule</artifactId>
    <version>0.9.33</version>
</dependency>

1.2 通过命令行工具安装

你可以通过下载 semver.jar 文件来使用命令行工具。下载后，你可以通过以下命令运行工具：

java -jar semver.jar --help

2. 项目的使用说明

2.1 命令行工具

semantic-versioning 提供了一个简单的命令行工具，用于检查 Java JAR 文件之间的 API 变化。以下是一些常用的命令：

• 显示帮助信息：

  java -jar semver.jar --help
  

• 显示两个 JAR 文件之间的差异：

  java -jar semver.jar --diff --base-jar previousJar --new-jar current.jar
  

• 检查两个 JAR 文件的兼容性：

  java -jar semver.jar --check --base-jar previousJar --new-jar current.jar
  

• 推断新 JAR 文件的版本：

  java -jar semver.jar --infer --base-version 1.0.0 --base-jar previous.jar --new-jar current.jar
  

• 验证 JAR 文件的版本是否符合语义化版本规范：

  java -jar semver.jar --validate --base-version 1.0.0 --base-jar previous.jar --new-version 1.0.1 --new-jar current.jar
  

2.2 Maven Enforcer 规则

semantic-versioning 还提供了一个 Maven Enforcer 规则，用于检查项目的版本是否符合语义化版本规范。你可以在 pom.xml 中配置该规则：

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <artifactId>maven-enforcer-plugin</artifactId>
        <version>1.0.1</version>
        ...
        <dependencies>
            ...
            <dependency>
                <groupId>org.semver</groupId>
                <artifactId>enforcer-rule</artifactId>
                <version>0.9.33</version>
            </dependency>
            ...
        </dependencies>
        ...
        <executions>
           ....
          <execution>
            <id>check</id>
            <phase>verify</phase>
            <goals>
              <goal>enforce</goal>
            </goals>
            <configuration>
              <rules>
                <requireSemanticVersioningConformance implementation="org.semver.enforcer.RequireSemanticVersioningConformance" />
              </rules>
            </configuration>
          </execution>
          ...
        </executions>
        ...
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

3. 项目API使用文档

3.1 API 概述

semantic-versioning 提供了一个 API，用于以编程方式验证项目的版本号是否符合语义化版本规范。以下是一个简单的示例：

final File previousJar = ...;
final File currentJar = ...;
        
final Comparer comparer = new Comparer(previousJar, currentJar, ..., ...);
final Delta delta = comparer.diff();

final String compatibilityType = ...;

// 验证计算的兼容性类型是否与提供的兼容性类型兼容
final Delta.CompatibilityType expectedCompatibilityType = Delta.CompatibilityType.valueOf(compatibilityType);
final Delta.CompatibilityType detectedCompatibilityType = delta.computeCompatibilityType();
if (detectedCompatibilityType.compareTo(expectedCompatibilityType) > 0) {
  // 不兼容
}

// 提供 previous 和 current Jar 文件的版本号
final Version previous = Version.parse(...);
final Version current = Version.parse(...);

// 验证当前版本号是否基于语义化版本原则有效
final boolean compatible = delta.validate(previous, current);

3.2 Maven Enforcer 规则 API

semantic-versioning 还提供了一个 Maven Enforcer 规则 API，用于检查项目的版本是否符合语义化版本规范。你可以在 pom.xml 中配置该规则：

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <artifactId>maven-enforcer-plugin</artifactId>
        <version>1.0.1</version>
        ...
        <dependencies>
            ...
            <dependency>
                <groupId>org.semver</groupId>
                <artifactId>enforcer-rule</artifactId>
                <version>0.9.33</version>
            </dependency>
            ...
        </dependencies>
        ...
        <executions>
           ....
          <execution>
            <id>check</id>
            <phase>verify</phase>
            <goals>
              <goal>enforce</goal>
            </goals>
            <configuration>
              <rules>
                <requireSemanticVersioningConformance implementation="org.semver.enforcer.RequireSemanticVersioningConformance" />
              </rules>
            </configuration>
          </execution>
          ...
        </executions>
        ...
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

4. 项目安装方式

4.1 通过 Maven 安装

在 Maven 项目中，你可以通过在 pom.xml 文件中添加以下依赖来安装 semantic-versioning：

<dependency>
    <groupId>org.semver</groupId>
    <artifactId>enforcer-rule</artifactId>
    <version>0.9.33</version>
</dependency>

4.2 通过命令行工具安装

你可以通过下载 semver.jar 文件来使用命令行工具。下载后，你可以通过以下命令运行工具：

java -jar semver.jar --help

通过以上步骤，你可以轻松安装并使用 semantic-versioning 来验证你的项目版本是否符合语义化版本规范。