Contributing
Sign the Contributor License Agreement
Spring Cloud 在非限制性 Apache 2.0 许可下发布,遵循非常标准的 Github 开发流程,使用 Github tracker 处理问题并将 pull request 合并到 main。如果您想贡献一些事情,即使是小事,请不要犹豫,但是要遵循以下准则。
Spring Cloud is released under the non-restrictive Apache 2.0 license, and follows a very standard Github development process, using Github tracker for issues and merging pull requests into main. If you want to contribute even something trivial please do not hesitate, but follow the guidelines below.
Sign the Contributor License Agreement
在接受非同小可的补丁程序或 pull request 之前,我们需要您签署贡献者许可协议。签署贡献者协议并不意味着任何人都有权向 main 存储库提交,但表示我们可以接受您的贡献,如果您这样做,您将获得作者的荣誉。可能会要求积极的贡献者加入核心团队,并获得合并 pull request 的能力。
Before we accept a non-trivial patch or pull request we will need you to sign the Contributor License Agreement. Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join the core team, and given the ability to merge pull requests.
Code of Conduct
本项目遵守贡献者守则。参与本项目,即表示您应该遵守该守则。请向 spring-code-of-conduct@pivotal.io 报告不可接受的行为。
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.
Code Conventions and Housekeeping
对于 pull request 来说,这些都不是必需的,但它们都将提供帮助。它们还可以在原始 pull request 之后但在合并之前添加。
None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge.
-
Use the Spring Framework code format conventions. If you use Eclipse you can import formatter settings using the
eclipse-code-formatter.xml
file from the Spring Cloud Build project. If using IntelliJ, you can use the Eclipse Code Formatter Plugin to import the same file. -
Make sure all new
.java
files to have a simple Javadoc class comment with at least an@author
tag identifying you, and preferably at least a paragraph on what the class is for. -
Add the ASF license header comment to all new
.java
files (copy from existing files in the project) -
Add yourself as an
@author
to the .java files that you modify substantially (more than cosmetic changes). -
Add some Javadocs and, if you change the namespace, some XSD doc elements.
-
A few unit tests would help a lot as well — someone has to do it.
-
If no-one else is using your branch, please rebase it against the current main (or other target branch in the main project).
-
When writing a commit message please follow these conventions, if you are fixing an existing issue please add
Fixes gh-XXXX
at the end of the commit message (where XXXX is the issue number).
Checkstyle
Spring Cloud Build 带有一组 checkstyle 规则。您可以在 spring-cloud-build-tools 模块中找到它们。该模块下最显着的文件是:
Spring Cloud Build comes with a set of checkstyle rules. You can find them in the spring-cloud-build-tools
module. The most notable files under the module are:
└── src ├── checkstyle │ └── checkstyle-suppressions.xml 3 └── main └── resources ├── checkstyle-header.txt 2 └── checkstyle.xml 1
1 | Default Checkstyle rules |
2 | File header setup |
3 | Default suppression rules |
Checkstyle configuration
Checkstyle 规则*在默认情况下处于禁用状态*。要将 checkstyle 添加到您的项目,只需定义以下属性和插件。
Checkstyle rules are disabled by default. To add checkstyle to your project just define the following properties and plugins.
<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 | Fails the build upon Checkstyle errors |
2 | Fails the build upon Checkstyle violations |
3 | Checkstyle analyzes also the test sources |
4 | Add the Spring Java Format plugin that will reformat your code to pass most of the Checkstyle formatting rules |
5 | Add checkstyle plugin to your build and reporting phases |
如果您需要禁止一些规则(例如,行长需要更长),那么您只需在项目目录下定义带有禁止规则的 ${project.root}/src/checkstyle/checkstyle-suppressions.xml 文件即可。例如:
If you need to suppress some rules (e.g. line length needs to be longer), then it’s enough for you to define a file under ${project.root}/src/checkstyle/checkstyle-suppressions.xml
with your suppressions. Example:
<?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 复制到您的项目。这样,一些默认格式化规则将得到应用。您可以通过运行此脚本执行此操作:
It’s advisable to copy the ${spring-cloud-build.rootFolder}/.editorconfig
and ${spring-cloud-build.rootFolder}/.springformat
to your project. That way, some default formatting rules will be applied. You can do so by running this script:
$ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/.editorconfig -o .editorconfig
$ touch .springformat
IDE setup
Intellij IDEA
要设置 Intellij,您应该导入我们的编码约定、检查配置文件并设置 checkstyle 插件。可以在 Spring Cloud Build项目中找到以下文件。
In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin. The following files can be found in the Spring Cloud Build project.
└── 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 | Default Checkstyle rules |
2 | File header setup |
3 | Default suppression rules |
4 | Project defaults for Intellij that apply most of Checkstyle rules |
5 | Project style conventions for Intellij that apply most of Checkstyle rules |
转到 文件
→ 设置
→ 编辑器
→ 代码样式
。在那里单击 方案
部分旁边的图标。在那里,单击 导入方案
值并选择 Intellij IDEA 代码样式 XML
选项。导入 spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml
文件。
Go to File
→ Settings
→ Editor
→ Code style
. There click on the icon next to the Scheme
section. There, click on the Import Scheme
value and pick the Intellij IDEA code style XML
option. Import the spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml
file.
转到 文件
→ 设置
→ 编辑器
→ 检查
。在那里单击 配置文件
部分旁边的图标。在那里,单击 导入配置文件
并导入 spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml
文件。
Go to File
→ Settings
→ Editor
→ Inspections
. There click on the icon next to the Profile
section. There, click on the Import Profile
and import the spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml
file.
为了让 Intellij 与 Checkstyle 协作,你必须安装 Checkstyle
插件。建议也安装 Assertions2Assertj
来自动转换 JUnit 断言
To have Intellij work with Checkstyle, you have to install the Checkstyle
plugin. It’s advisable to also install the Assertions2Assertj
to automatically convert the JUnit assertions
转到 文件
→ 设置
→ 其他设置
→ Checkstyle
。在那里单击 配置文件
部分中的 +
图标。在那里,你必须定义从中选取 checkstyle 规则的位置。在上图中,我们从克隆的 Spring Cloud Build 仓库中选择了规则。然而,你可以指向 Spring Cloud Build 的 GitHub 仓库(例如,对于 checkstyle.xml
:https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/main/resources/checkstyle.xml
)。我们需要提供以下变量:
Go to File
→ Settings
→ Other settings
→ Checkstyle
. There click on the +
icon in the Configuration file
section. There, you’ll have to define where the checkstyle rules should be picked from. In the image above, we’ve picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build’s GitHub repository (e.g. for the checkstyle.xml
: https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/main/resources/checkstyle.xml
). We need to provide the following variables:
-
checkstyle.header.file
- please point it to the Spring Cloud Build’s,spring-cloud-build-tools/src/main/resources/checkstyle-header.txt
file either in your cloned repo or via thehttps://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt
URL. -
checkstyle.suppressions.file
- default suppressions. Please point it to the Spring Cloud Build’s,spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml
file either in your cloned repo or via thehttps://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml
URL. -
checkstyle.additional.suppressions.file
- this variable corresponds to suppressions in your local project. E.g. you’re working onspring-cloud-contract
. Then point to theproject-root/src/checkstyle/checkstyle-suppressions.xml
folder. Example forspring-cloud-contract
would be:/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml
.
请记住将 Scan Scope
设置为 All sources
,因为我们对生产和测试源代码应用 Checkstyle 规则。
Remember to set the Scan Scope
to All sources
since we apply checkstyle rules for production and test sources.
Duplicate Finder
Spring Cloud Build 带来了 basepom:duplicate-finder-maven-plugin
,它可以在 Java 类路径中标记重复的和冲突的类和资源。
Spring Cloud Build brings along the basepom:duplicate-finder-maven-plugin
, that enables flagging duplicate and conflicting classes and resources on the java classpath.
Duplicate Finder configuration
重复项查找器 默认启用,并将在 Maven 构建的 verify
阶段运行,但它仅在你将 duplicate-finder-maven-plugin
添加到项目的 pom.xml
的 build
部分时才在你的项目中生效。
Duplicate finder is enabled by default and will run in the verify
phase of your Maven build, but it will only take effect in your project if you add the duplicate-finder-maven-plugin
to the build
section of the projecst’s pom.xml
.
<build>
<plugins>
<plugin>
<groupId>org.basepom.maven</groupId>
<artifactId>duplicate-finder-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
对于其他属性,我们已设置 plugin documentation中列出的默认值。
For other properties, we have set defaults as listed in the plugin documentation.
你可以通过设置以 duplicate-finder-maven-plugin
为前缀的选定属性值轻松覆盖它们。例如,将 duplicate-finder-maven-plugin.skip
设置为 true
以在你的构建中跳过重复检查。
You can easily override them but setting the value of the selected property prefixed with duplicate-finder-maven-plugin
. For example, set duplicate-finder-maven-plugin.skip
to true
in order to skip duplicates check in your build.
如果你需要将 ignoredClassPatterns
或 ignoredResourcePatterns
添加到你的设置中,请确保在项目的插件配置部分中添加它们:
If you need to add ignoredClassPatterns
or ignoredResourcePatterns
to your setup, make sure to add them in the plugin configuration section of your project:
<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>