20. 贡献

Spring Cloud 在 Apache 2.0 许可证（非限制性许可证）下发布，遵循标准的 GitHub 开发流程，使用 GitHub 的问题追踪系统处理问题，并将拉取请求合并到主分支中。如果您希望贡献哪怕是最微小的改进，请不要犹豫，但请遵守以下指南。spring-doc.cadn.net.cn

20.1. 签署贡献者许可协议

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

20.2. 行为准则

此项目遵循贡献者公约代码 行为准则 。 通过参与，您应该遵守该代码。 如果您有 unacceptable 的行为，请向 [email protected] 报告。 spring-doc.cadn.net.cn

20.3. 代码约定和日常维护

这些都不是拉取请求所必需的，但它们都会有所帮助。它们也可以在原始拉取请求之后、合并之前添加。spring-doc.cadn.net.cn

  • 使用 Spring Framework 的代码格式约定。如果您使用 Eclipse，可以使用来自 Spring Cloud Build 项目的 eclipse-code-formatter.xml 文件导入格式化设置。如果使用 IntelliJ，可以使用 Eclipse Code Formatter 插件 导入同一文件。spring-doc.cadn.net.cn

  • 确保所有新 .java 文件都包含一个简单的 Javadoc 类注释，其中至少包含一个 @author 标签以标识作者，并且最好还包含一段文字说明该类的用途。spring-doc.cadn.net.cn

  • 为所有新文件添加 ASF 许可证头注释（从项目中现有文件复制）spring-doc.cadn.net.cn

  • 将您自己作为 @author 添加到您进行实质性修改（超过表面性改动）的 .java 文件中。spring-doc.cadn.net.cn

  • 添加一些 Javadoc 文档，如果更改了命名空间，则还需添加一些 XSD 文档元素。spring-doc.cadn.net.cn

  • 一些单元测试也会有很大帮助——总得有人来做这件事。spring-doc.cadn.net.cn

  • 如果没有人正在使用您的分支，请将其重新基于当前的主分支（或主项目中的其他目标分支）进行变基。spring-doc.cadn.net.cn

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

20.4. Checkstyle

Spring Cloud Build 自带一组 Checkstyle 规则。您可以在 spring-cloud-build-tools 模块中找到它们。该模块下最值得注意的文件包括：spring-doc.cadn.net.cn

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

20.4.1. 配置Checkstyle

Checkstyle 规则默认是禁用的。要将 Checkstyle 添加到您的项目中，只需定义以下属性和插件即可。spring-doc.cadn.net.cn

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 格式插件，该插件可重新格式化您的代码，使其通过大多数 Checkstyle 格式化规则。
5 将 Checkstyle 插件添加到您的构建和报告阶段

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

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 复制到您的项目中。这样，一些默认的格式化规则将会被应用。您可以通过运行以下脚本实现：spring-doc.cadn.net.cn

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

20.5. IDE 配置

20.5.1. Intellij IDEA

为了设置 IntelliJ，您应该导入我们的编码规范、检查配置文件并配置 Checkstyle 插件。
以下文件可以在 Spring Cloud Build 项目中找到。spring-doc.cadn.net.cn

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
Figure 1. Code style

前往 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 文件。spring-doc.cadn.net.cn

Code style
图 2. 检查配置文件

转到File→Settings→Editor→Inspections。单击Profile部分旁边图标的Import Profile，然后导入spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml文件。spring-doc.cadn.net.cn

检查样式

为使 IntelliJ 与 Checkstyle 兼容，你需要安装 Checkstyle 插件。建议同时安装 Assertions2Assertj 以自动转换 JUnit 断言spring-doc.cadn.net.cn

Checkstyle

Go to File → Settings → Other settings → Checkstyle。在这里，单击+图标在Configuration file部分。在那里，您必须定义检查样式规则应从何处获取。在上图中，我们从克隆的Spring Cloud Build存储库中选择了规则。但是，您可以指向Spring Cloud Build的GitHub存储库（例如，在checkstyle.xml中：raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml]。我们需要提供以下变量：spring-doc.cadn.net.cn

请记得将 Scan Scope 设置为 All sources ，因为我们对生产源代码和测试源代码应用检查风格规则。spring-doc.cadn.net.cn

20.6. 重复查找器

Spring Cloud Build 带来了 basepom:duplicate-finder-maven-plugin，它能够检测类路径上的重复和冲突类和资源。spring-doc.cadn.net.cn

20.6.1. 重复查找器配置

重复检测默认情况下是< strong >启用的 ，将在Maven构建的< code >0 阶段运行，但只有在您向< code >1 中添加< code >2 时才会对项目产生影响。 spring-doc.cadn.net.cn

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

对于其他属性，我们已按照插件文档中列出的默认值进行设置。spring-doc.cadn.net.cn

你可以轻松地通过设置前缀为duplicate-finder-maven-plugin的选定属性的值来覆盖它们。例如，要跳过构建中的重复项检查，请将duplicate-finder-maven-plugin.skip设置为true。spring-doc.cadn.net.cn

如果需要在设置中添加ignoredClassPatterns或ignoredResourcePatterns，请确保在项目的插件配置部分进行添加：spring-doc.cadn.net.cn

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