贡献

Spring Cloud 基于非限制性的 Apache 2.0 许可发布，并遵循标准的 Github 开发流程，使用 Github issue 跟踪器进行问题跟踪，并将 pull requests 合并到 main 分支。即使您想贡献一些微不足道的内容，也请不要犹豫，但请遵循以下指南。

开发者原创证明 (DCO)

所有提交都必须在每个提交信息的末尾包含 *Signed-off-by* 尾部信息，以表明贡献者同意开发者原创证明。更多详细信息，请参阅博客文章 你好 DCO，再见 CLA：简化对 Spring 的贡献。

行为准则

本项目遵循贡献者公约 行为准则。通过参与本项目，您应遵守此准则。请将不可接受的行为报告给 [email protected]。

代码规范和整理

这些对于 pull request 来说并非必需，但它们都会有所帮助。它们也可以在原始 pull request 之后但在合并之前添加。

  • 使用 Spring Framework 的代码格式规范。如果您使用 Eclipse，可以使用 Spring Cloud Build 项目中的 eclipse-code-formatter.xml 文件导入格式化设置。如果您使用 IntelliJ，可以使用 Eclipse Code Formatter Plugin 插件导入相同的文件。

  • 确保所有新的 .java 文件都有一个简单的 Javadoc 类注释，至少包含一个 @author 标签以标识您，最好还有一个段落说明该类的用途。

  • 在所有新的 .java 文件中添加 ASF 许可证头部注释（从项目中的现有文件复制）

  • 对于您进行了实质性修改（不仅仅是表面更改）的 .java 文件，请将自己添加为 @author。

  • 添加一些 Javadocs，如果您更改了命名空间，请添加一些 XSD 文档元素。

  • 一些单元测试也会有很大帮助 — — 总得有人做这件事。

  • 如果没有其他人正在使用您的分支，请将其基于当前的 main 分支（或主项目中的其他目标分支）进行 rebase。

  • 在编写提交信息时，请遵循 这些规范；如果您正在修复现有问题，请在提交信息的末尾添加 Fixes gh-XXXX（其中 XXXX 是问题编号）。

Checkstyle

Spring Cloud Build 提供了一套 checkstyle 规则。您可以在 spring-cloud-build-tools 模块中找到它们。该模块下最值得注意的文件有

spring-cloud-build-tools/
└── src
    ├── checkstyle
    │   └── checkstyle-suppressions.xml (3)
    └── main
        └── resources
            ├── checkstyle-header.txt (2)
            └── checkstyle.xml (1)
1 默认 Checkstyle 规则
2 文件头部设置
3 默认抑制规则

Checkstyle 配置

Checkstyle 规则默认是 禁用 的。要将 checkstyle 添加到您的项目中，只需定义以下属性和插件。

pom.xml
<properties>
<maven-checkstyle-plugin.failsOnError>true</maven-checkstyle-plugin.failsOnError> (1)
        <maven-checkstyle-plugin.failsOnViolation>true
        </maven-checkstyle-plugin.failsOnViolation> (2)
        <maven-checkstyle-plugin.includeTestSourceDirectory>true
        </maven-checkstyle-plugin.includeTestSourceDirectory> (3)
</properties>

<build>
        <plugins>
            <plugin> (4)
                <groupId>io.spring.javaformat</groupId>
                <artifactId>spring-javaformat-maven-plugin</artifactId>
            </plugin>
            <plugin> (5)
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-checkstyle-plugin</artifactId>
            </plugin>
        </plugins>

    <reporting>
        <plugins>
            <plugin> (5)
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-checkstyle-plugin</artifactId>
            </plugin>
        </plugins>
    </reporting>
</build>
1 在 Checkstyle 错误时使构建失败
2 在 Checkstyle 违规时使构建失败
3 Checkstyle 也分析测试源代码
4 添加 Spring Java Format 插件，它将重新格式化您的代码，使其通过大部分 Checkstyle 格式规则
5 将 checkstyle 插件添加到您的构建和报告阶段

如果您需要抑制某些规则（例如，行长度需要更长），则只需在 ${project.root}/src/checkstyle/checkstyle-suppressions.xml 下定义一个包含您抑制规则的文件即可。示例

projectRoot/src/checkstyle/checkstyle-suppresions.xml
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
		"-//Puppy Crawl//DTD Suppressions 1.1//EN"
		"https://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
<suppressions>
	<suppress files=".*ConfigServerApplication\.java" checks="HideUtilityClassConstructor"/>
	<suppress files=".*ConfigClientWatch\.java" checks="LineLengthCheck"/>
</suppressions>

建议将 ${spring-cloud-build.rootFolder}/.editorconfig 和 ${spring-cloud-build.rootFolder}/.springformat 复制到您的项目中。这样，一些默认的格式化规则将得到应用。您可以通过运行此脚本来完成此操作

$ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/.editorconfig -o .editorconfig
$ touch .springformat

IDE 设置

Intellij IDEA

为了设置 Intellij，您应该导入我们的代码规范、检查配置文件并设置 checkstyle 插件。以下文件可以在 Spring Cloud Build 项目中找到。

spring-cloud-build-tools/
└── src
    ├── checkstyle
    │   └── checkstyle-suppressions.xml (3)
    └── main
        └── resources
            ├── checkstyle-header.txt (2)
            ├── checkstyle.xml (1)
            └── intellij
                ├── Intellij_Project_Defaults.xml (4)
                └── Intellij_Spring_Boot_Java_Conventions.xml (5)
1 默认 Checkstyle 规则
2 文件头部设置
3 默认抑制规则
4 适用于 Intellij 的项目默认设置，应用了大部分 Checkstyle 规则
5 适用于 Intellij 的项目样式约定，应用了大部分 Checkstyle 规则
Code style
图 1. 代码样式

前往 File → Settings → Editor → Code style。点击 Scheme 部分旁边的图标。在那里，点击 Import Scheme 值并选择 Intellij IDEA code style XML 选项。导入文件 spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml。

Code style
图 2. 检查配置文件

前往 File → Settings → Editor → Inspections。点击 Profile 部分旁边的图标。在那里，点击 Import Profile 并导入文件 spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml。

Checkstyle

要让 Intellij 与 Checkstyle 配合使用，您必须安装 Checkstyle 插件。建议同时安装 Assertions2Assertj 以自动转换 JUnit 断言

Checkstyle

前往 File → Settings → Other settings → Checkstyle。点击 Configuration file 部分中的 + 图标。在那里，您需要定义 checkstyle 规则应从何处获取。在上面的图片中，我们从克隆的 Spring Cloud Build 仓库中获取了规则。但是，您可以指向 Spring Cloud Build 的 GitHub 仓库（例如对于 checkstyle.xml：raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/main/resources/checkstyle.xml）。我们需要提供以下变量

请记住将 Scan Scope 设置为 All sources，因为我们将 checkstyle 规则应用于生产和测试源代码。

重复查找器

Spring Cloud Build 引入了 basepom:duplicate-finder-maven-plugin 插件，它能够标记 Java classpath 中重复和冲突的类和资源。

重复查找器配置

Duplicate finder 默认是 启用 的，并将在 Maven 构建的 verify 阶段运行，但只有当您将 duplicate-finder-maven-plugin 添加到项目 pom.xml 的 build 部分时，它才会在您的项目中生效。

pom.xml
<build>
    <plugins>
        <plugin>
            <groupId>org.basepom.maven</groupId>
            <artifactId>duplicate-finder-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

对于其他属性，我们已按照 插件文档 中列出的设置了默认值。

您可以通过设置以 duplicate-finder-maven-plugin 为前缀的选定属性的值来轻松覆盖它们。例如，将 duplicate-finder-maven-plugin.skip 设置为 true 以跳过构建中的重复检查。

如果您的设置需要添加 ignoredClassPatterns 或 ignoredResourcePatterns，请确保将其添加到您项目的插件配置部分

<build>
    <plugins>
        <plugin>
            <groupId>org.basepom.maven</groupId>
            <artifactId>duplicate-finder-maven-plugin</artifactId>
            <configuration>
                <ignoredClassPatterns>
				    <ignoredClassPattern>org.joda.time.base.BaseDateTime</ignoredClassPattern>
					<ignoredClassPattern>.*module-info</ignoredClassPattern>
				</ignoredClassPatterns>
                <ignoredResourcePatterns>
                    <ignoredResourcePattern>changelog.txt</ignoredResourcePattern>
                </ignoredResourcePatterns>
            </configuration>
        </plugin>
    </plugins>
</build>