貢獻

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>