贡献指南

Spring Cloud 采用非限制性 Apache 2.0 许可证发布，并遵循非常标准的 Github 开发流程，使用 Github 的问题追踪器来管理问题，并将拉取请求合并到主分支。如果您想贡献任何内容，即使是很小的改动，也请不要犹豫，但请遵循以下指南。

签署贡献者许可协议

在我们接受任何重要的补丁或拉取请求之前，我们需要您签署贡献者许可协议。签署贡献者协议不会授予任何人对主仓库的提交权限，但这意味着我们可以接受您的贡献，如果您这样做，您将获得作者署名。活跃的贡献者可能会被邀请加入核心团队，并被授予合并拉取请求的能力。

行为准则

此项目遵守贡献者公约行为准则。参与此项目即表示您同意遵守此准则。请将不可接受的行为报告给[email protected]。

代码规范和维护

这些都不是拉取请求的必要条件，但它们都会有所帮助。这些也可以在原始拉取请求之后，但在合并之前添加。

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

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

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

  • 如果您对.java文件进行了实质性修改（超过简单的代码美化），请将自己添加为@author。

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

  • 一些单元测试也会非常有帮助——总得有人去做。

  • 如果没有人使用您的分支，请将其重新定位到当前的主分支（或主项目中的其他目标分支）。

  • 编写提交信息时，请遵循这些约定，如果您正在修复现有问题，请在提交信息末尾添加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. 代码样式

转到文件→设置→编辑器→代码样式。单击“方案”部分旁边的图标。在那里，单击“导入方案”值并选择“Intellij IDEA 代码样式 XML”选项。导入spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml文件。

Code style
图 2. 检查配置文件

转到文件→设置→编辑器→检查。单击“配置文件”部分旁边的图标。在那里，单击“导入配置文件”并导入spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml文件。

Checkstyle

要使 Intellij 使用 Checkstyle，您必须安装Checkstyle插件。建议还安装Assertions2Assertj来自动转换 JUnit 断言

Checkstyle

转到文件→设置→其他设置→Checkstyle。单击“配置文件”部分中的“+”图标。在那里，您必须定义应从中选择 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）。我们需要提供以下变量：

请记住将扫描范围设置为所有源代码，因为我们将 Checkstyle 规则应用于生产和测试源代码。

重复查找器

Spring Cloud Build 自带basepom:duplicate-finder-maven-plugin插件，用于标记 Java 类路径上重复和冲突的类和资源。

重复查找器配置

重复查找器**默认启用**，并在 Maven 构建的verify阶段运行，但只有在项目的pom.xml文件的build部分添加了duplicate-finder-maven-plugin插件后，它才会在您的项目中生效。

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>