本黑客指南概述開發人員如何參與貢獻 Apache ActiveMQ Artemis 專案。

1. 使用程式碼

雖然 Apache ActiveMQ Artemis 的標準 Git 儲存庫託管在 Apache 硬體上的 https://gitbox.apache.org/repos/asf/activemq-artemis.git，但鼓勵 (但非必要) 貢獻者使用 GitHub 上的鏡像進行協作和提取請求審閱功能。請按照以下步驟設定 GitHub 等。

如果您因任何原因不想使用 GitHub，您可以按照下面「典型的開發週期」部分概述的整體流程，但改為將修補程式檔案附加到相關的 JIRA 或電子郵件至 開發人員列表。

1.1. 初始步驟

  1. 如果您還沒有 GitHub 帳戶，請建立一個

    https://github.com

  2. 將 apache-artemis 儲存庫分叉到您的帳戶中

    https://github.com/apache/activemq-artemis

  3. 將您新分叉的副本複製到您的本機工作區

    $ git clone git@github.com:<your-user-name>/activemq-artemis.git
Cloning into 'activemq-artemis'...
remote: Counting objects: 63800, done.
remote: Compressing objects: 100% (722/722), done.
remote: Total 63800 (delta 149), reused 0 (delta 0), pack-reused 62748
Receiving objects: 100% (63800/63800), 18.28 MiB | 3.16 MiB/s, done.
Resolving deltas: 100% (28800/28800), done.
Checking connectivity... done.

$ cd activemq-artemis

  4. 為 upstream 新增遠端參考，以提取未來的更新

    $ git remote add upstream https://github.com/apache/activemq-artemis

  5. 使用 Maven 建置

    通常，開發人員會想要使用 dev 設定檔進行建置，該設定檔會啟用授權和程式碼樣式檢查。例如

    $ mvn -Pdev install
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] ActiveMQ Artemis Parent ........................... SUCCESS [2.298s]
[INFO] ActiveMQ Artemis Commons .......................... SUCCESS [1.821s]
[INFO] ActiveMQ Artemis Selector Implementation .......... SUCCESS [0.767s]
[INFO] ActiveMQ Artemis Native POM ....................... SUCCESS [0.189s]
[INFO] ActiveMQ Artemis Journal .......................... SUCCESS [0.646s]
[INFO] ActiveMQ Artemis Core Client ...................... SUCCESS [5.969s]
[INFO] ActiveMQ Artemis JMS Client ....................... SUCCESS [2.110s]
[INFO] ActiveMQ Artemis Server ........................... SUCCESS [11.540s]
...
[INFO] ActiveMQ Artemis stress Tests ..................... SUCCESS [0.332s]
[INFO] ActiveMQ Artemis performance Tests ................ SUCCESS [0.174s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

1.2. 典型的開發週期

  1. 識別一項任務 (例如要修正的錯誤或要實作的功能)

    https://issues.apache.org/jira/browse/ARTEMIS

  2. 在您的本機 Git 儲存庫中建立一個主題分支以進行您的工作

    $ git checkout -b my_cool_feature

  3. 進行變更並提交一次或多次

    $ git commit

    當您提交變更時，您需要提供提交訊息。我們遵循 官方 Git 書籍中建議的 50/72 Git 提交訊息格式。ActiveMQ Artemis 提交訊息應按以下方式格式化

    1. 新增第一行，其中包含摘要，最多使用 50 個字元。摘要開頭為 JIRA 金鑰 (ARTEMIS-XXX)，後接簡短的變更描述。僅對於非常小的無關緊要的變更 (例如錯字或小型文件修正) 使用前綴 NO-JIRA。錯誤修正、功能或任何程式碼變更，實際上都應附帶 JIRA，以便可以在發行說明中清楚地報告它們。

    2. 在第一行後插入一個空白行。

    3. 在以下各行中提供變更的詳細描述，並在需要時中斷段落。這些行應在 72 個字元處換行。

      一個格式正確的提交訊息範例

      ARTEMIS-123 Add new commit msg format to README

Adds a description of the new commit message format as well as examples
of well formatted commit messages to the README.md.  This is required
to enable developers to quickly identify what the commit is intended to
do and why the commit was added.

  4. 有時您會想要將您的提交推送到 GitHub 以進行安全保留和/或與他人分享。

    $ git push origin my_cool_feature

    請注意，Git 推送會參考您正在推送的分支，並且預設為 main，而不是您的工作分支。

  5. 討論您計劃的變更 (如果您想要意見反應)

  6. 一旦您完成功能/修正的編碼，則將您的分支重新調整到最新的主分支 (將您的修補程式應用在主分支之上)

    $ git fetch upstream
$ git rebase -i upstream/main

    如果您有衝突，請修正它們並重新執行 rebase。-f 強制推送並更改歷史記錄。請參閱下面的註解

    $ git push -f origin my_cool_feature

    rebase -i 會觸發互動式更新，這也允許您合併提交、更改提交訊息等。最好使提交記錄對於外部使用而言非常良好 (例如，將所有相關的提交合併為單個提交)。請注意，重新調整基準和/或使用 push -f 會更改歷史記錄。雖然這對於製作乾淨的修補程式來說很好，但對於任何分叉您的分支的人來說都不太友善。因此，您會想要確保您在您不共享的分支中工作，或者如果您確實共享它，則告訴他們您將要修改分支歷史記錄 (因此，他們將需要在您推送它之後在您的分支之上重新調整基準)。

  7. 將您的變更合併到上游

    1. 在您儲存庫的分叉中，按一下提取請求連結，以傳送 GitHub 提取請求。

    2. 電子郵件將自動傳送給 ActiveMQ 開發人員列表。

    3. 在審閱過程中，您可能會在您的請求中看到自動測試執行註解。

    4. 在審閱之後，維護者會將您的 PR 合併到標準 Git 儲存庫中，此時這些變更將與 GitHub 鏡像儲存庫 (即您的 main) 同步，並且您的 PR 將由 asfgit 機器人關閉。

1.3. 其他常見任務

  1. 從上游提取更新

    $ git pull --rebase upstream main

    (--rebase 會自動將您的本機提交 (如果有的話) 移動到您提取的最新分支之上；如果您沒有任何本機提交，則可以將其關閉)。

    最後一個選項，有些人更喜歡，是完全避免使用提取，而只是使用提取 + 重新調整基準 (這當然需要更多輸入)。例如

    $ git fetch upstream
$ git pull

  2. 將提取的更新 (如果您未使用主題分支，則為本機提交) 推送到您的私人 GitHub 儲存庫 (來源)

    $ git push
Counting objects: 192, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (44/44), done.
Writing objects: 100% (100/100), 10.67 KiB, done.
Total 100 (delta 47), reused 100 (delta 47)
To git@github.com:<your-user-name>/apache-artemis.git
3382570..1fa25df  main -> main

    您可能需要指定 -f 以強制變更。

1.4. 新增相依性

由於某些開放原始碼授權與 Apache v2.0 授權 (本專案依據的授權) 之間的不相容性，因此在向專案新增新的相依性時必須小心。Apache 軟體基金會的第三方授權原則在此處有更多資訊：https://www.apache.org/legal/3party.html

為了追蹤 ActiveMQ Artemis 中的所有授權，必須在最上層的 pom.xml 或 test/pom.xml 中新增新的相依性 (取決於這是否為僅測試相依性，或者是否在主要程式碼庫中使用)。相依性應在相依性管理部分下新增，其中包含版本，並使用註解標示相依性版本的授權。請參閱主要 pom.xml 中的現有相依性以獲取範例。然後，可以將相依性新增到個別的 ActiveMQ Artemis 模組，無需指定版本 (版本是從最上層 pom 的相依性管理部分推斷出來的)。這允許 ActiveMQ Artemis 開發人員追蹤所有相依性和授權。

2. IDE 整合

在已檢查的資料夾上的 ./etc/ide-settings 下有一些對 IDE 整合有用的檔案。此資料夾不是來源發行版的一部分，但可以輕鬆取得

2.1. IntelliJ IDEA

2.1.1. 匯入專案

以下步驟說明如何在 IntelliJ IDEA 中開啟 ActiveMQ Artemis Maven 專案，並設定正確的 Maven 設定檔，以允許從 IDE 執行 JUnit 測試。(步驟基於版本：2018.2)

  • 從乾淨的複製開始

  • 使用 Maven 'dev' 設定檔建置 activemq-artemis 來源

    $ mvn -Pdev install -DskipTests

  • 等待並確保結果為 BUILD SUCCESS

  • 啟動 IntelliJ

  • 從「歡迎使用 IntelliJ IDEA」畫面選取「開啟」

  • 從「開啟檔案或專案」畫面選取複製的 activemq-artemis 目錄中的 pom.xml 檔案

  • 從「開啟專案」畫面選取「以專案開啟」

這應該會開啟主要的 IntelliJ IDEA 視窗，您會注意到透過底部狀態列執行的某些背景工作。這些背景工作應會成功匯入專案並自動建立索引。

一旦專案已匯入，且 IntelliJ IDEA 已趕上匯入所有相關的相依性，您應該能夠從 IDE 執行 JUnit 測試。選取測試 -> 整合測試資料夾中的任何測試類別。在專案索引標籤中以滑鼠右鍵按一下該類別，然後按一下「執行 <類別名稱>」。如果存在「執行 <類別名稱>」選項，則表示您已準備就緒。

2.1.2. 關於 IDEA 上 IBM JDK 的注意事項

如果您正在執行 IBM JDK，則可能很難使其正常運作。

在您將 JDK 新增至 IDE 後，也請在該 JDK 下新增特定於您平台的 vm.jar (例如 JAVA_HOME/jre/lib/amd64/default/jclSC180/vm.jar)。

有一個關於此問題的 StackOverflow 問題，如果您遇到此問題，它可能會很有用。

2.1.3. IDEA 的樣式範本和檢查設定

我們已分享適用於此專案的樣式範本。如果您想要應用它們，請使用這些步驟

  • 檔案 -> 匯入設定

  • 選取 ./artemis-cloned-folder/etc/ide-settings/idea/IDEA-style.jar 下的檔案

  • 選取「程式碼樣式範本」和「檔案範本」 (這是預設選項)

  • 選取「確定」並重新啟動 IDEA

或者，您可以將 artemis-codestyle.xml 複製到您主設定中的 IntelliJIdea15/codestyles 下。

若要匯入檢查設定：

  • 檔案 -> 設定 -> 編輯器 -> 檢查 -> 管理 -> 匯入

  • 選取檔案 ./artemis-cloned-folder/etc/ide-settings/idea/artemis-inspections.xml

  • 選取「確定」

2.1.4. 問題：我的 JUnit 測試無法在 IDE 中執行。

如果不存在「執行 <類別名稱>」或「執行所有測試」選項，則很可能未正確匯入預設設定檔。若要 (重新) 在現有專案中匯入「測試」Maven 設定檔，請執行下列步驟

  • 開啟 Maven 專案工具視窗：檢視 -> 工具視窗 -> Maven 專案

  • 選取「設定檔」下拉式清單

  • 取消選取，然後重新選取「測試」旁邊的核取方塊。

  • 按一下視窗左上角的「重新匯入所有 Maven 專案」按鈕。它看起來像一個圓形的藍色箭頭。

  • 等待 IDEA 重新載入，然後再次嘗試執行 JUnit 測試。現在應該會出現執行選項。

2.2. Eclipse

我們建議使用 Eclipse Kepler (4.3)，因為它內建支援 Maven 和 Git。請注意，即使在 Eclipse Kepler (4.3) 中，子專案 (例如文件) 使用的某些 Maven 外掛程式仍然不受支援。

Eclipse m2e 已包含在「適用於 Java 開發人員的 Eclipse IDE」中，或者可以從 Eclipse Kepler 發行儲存庫安裝。

2.2.1. Git 設定

強烈建議關閉 Git Team 擴充功能自動更新 .gitignore 檔案的功能。否則，它會在許多不需要的目錄中生成新的 .gitignore 檔案，因為頂層目錄已有 .gitignore 檔案。要關閉此功能，請前往「偏好設定 (Preferences) -> 團隊 (Team) -> Git -> 專案 (Projects)」，然後取消選取「自動忽略衍生的資源 (Automatically ignore derived resources)」核取方塊。

2.2.2. Schema 設定

為了正確進行 schema 驗證，您可以將 Artemis schema 新增到您的 Eclipse XML Catalog 中

  • 開啟：視窗 (Window) -> 偏好設定 (Preferences) -> XML -> XML Catalog

  • 選取「新增 (Add)」->「工作區 (Workspace)」-> 導覽至 artemis-server 並選取 src/main/resources/schema/artemis-server.xsd -> 按一下「確定 (OK)」

  • 重複上述步驟，並新增 src/main/resources/schema/artemis-configuration.xsd

2.2.3. Checkstyle 設定

您可以將 Artemis Checkstyle 範本匯入 Eclipse 中以進行 Checkstyle 驗證。作為先決條件，您需要確保 Checkstyle 外掛程式已安裝到 Eclipse 中，您可以從 Eclipse Marketplace 取得該外掛程式。您還需要設定 Sevntu-Checkstyle。請參閱 https://sevntu-checkstyle.github.io/sevntu.checkstyle/ 以取得說明。然後設定範本

  • 開啟：視窗 (Window) -> 偏好設定 (Preferences) -> Checkstyle

  • 在「類型 (Type)」下拉式選單中選取「新增 (New) -> 專案相關設定 (Project Relative Configuration)」

  • 給設定一個名稱，並在「位置 (Location)」下方輸入 "/artemis-pom/etc/checkstyle.xml"，然後按一下「確定 (ok)」

  • 現在您應該會在 Checkstyle 設定檔列表中看到新的設定。如果需要，您可以選取新的設定作為預設值。

2.2.4. 註解預處理

ActiveMQ Artemis 使用 JBoss Logging，這需要從 Java 註解產生原始碼。為了使其在 Eclipse 中「正常運作」，您需要安裝 Maven Integration for Eclipse JDT Annotation Processor Toolkit m2e-apt。請參閱 JBoss 部落格文章 以取得詳細資訊。

2.2.5. 從 Eclipse 執行測試

在上述章節中設定註解預處理是您在「unit-tests」專案中執行測試所需的全部，因為這會將產生的記錄器正確新增至原始碼。但是，要在其他專案（例如「performance-tests」或「integration-tests」，它們依賴於「unit-tests」）中執行測試，則需要額外一個步驟。目前，m2eclipse 無法正確連結來自「unit-tests」的產生來源註解資料夾，導致產生的記錄器不可用。解決此問題的最簡單方法是手動將「unit-tests」專案相依性新增到您想要從中執行測試類別的每個專案中

  • 在測試專案 (例如 integration-tests) 上按一下滑鼠右鍵：內容 (Properties) -> Java 建置路徑 (Java Build Path) -> 專案 (Projects) -> 新增 (Add)

  • 選取「unit-tests」專案，然後按一下「確定 (Ok)」

現在您應該可以執行測試，前提是先前步驟已正確設定註解預處理。

2.2.6. Javacc-Maven-Plugin 的 M2E 連接器

Eclipse Indigo (3.7) 具備現成的支援。

在撰寫本文時，Eclipse Kepler (4.3) 仍然缺少對 Maven javacc 外掛程式的支援。可用的 javacc-maven-plugin 的 m2e 連接器 需要降級 Maven 元件才能安裝。手動安裝說明（在撰寫本文時，您需要使用開發更新網站）。請參閱 這篇文章，了解如何在 Eclipse Juno (4.2) 中執行此操作。

Eclipse Kepler 目前建議的解決方案是將 javacc-maven-plugin 標示為 Eclipse 忽略，從命令列執行 Maven，然後修改專案 activemq-core-client，將資料夾 target/generated-sources/javacc 新增至其建置路徑。

2.2.7. 使用專案工作集

匯入所有 ActiveMQ Artemis 子專案將在 Eclipse 中建立過多專案，使您的套件瀏覽器和專案瀏覽器視圖雜亂不堪。解決此問題的一種方法是使用 Eclipse 的工作集 功能。在 Dzone 關於 Eclipse 工作集的文章 中可以找到其良好介紹。

3. 建置

我們使用 Apache Maven 來建置程式碼、發行版等，並管理相依性。

最低要求的 Maven 版本為 3.0.0。

請注意，仍有一些 與 Maven 3.X 的相容性問題 尚未解決。對於 「site」外掛程式 尤其如此。

3.1. 完整發行版

要建置包含文件和 JavaDocs 的完整發行版

$ mvn -Prelease package

將其安裝到您的本機 maven 儲存庫

$ mvn -Prelease install

對於任何建置，您可以使用 -DskipTests 跳過測試，這會使建置速度快得多，例如：

$ mvn -Prelease package -DskipTests

3.2. 不含文件的完整發行版

可以建置不含手冊和 Javadoc 的發行版。只需執行

$ mvn package

3.3. 僅限文件

從 artemis-website 模組執行

$ mvn -Prelease package

這將建置使用者手冊（HTML 和 PDF）、移轉指南、駭客指南和 JavaDocs。輸出將分別放在 target/classes/user-manual、target/classes/migration-guide、target/classes/hacking-guide 和 target/apidocs 目錄中。

產生使用者手冊的 PDF 會使建置時間增加近一分鐘，因此可以使用 -DskipWebsitePdfGeneration 跳過此步驟。

3.4. 離線

$ mvn dependency:go-offline
$ mvn -o ...

3.5. 建置 ASYNC IO 程式庫

ActiveMQ Artemis 提供 ASYNCIO journal-type，它與 Linux 核心 libaio 程式庫互動。應盡可能使用 ASYNCIO 日誌類型，因為它在效能方面遠勝於其他類型。

ActiveMQ Artemis 未在原始碼發行版中隨附 Artemis Native ASYNCIO 程式庫。這需要在執行 mvn install 之前建置，以確保 ASYNCIO 日誌類型在產生的建置中可用。如果您不想使用 ASYNCIO 或您的系統不支援 libaio，請勿擔心，ActiveMQ Artemis 將在執行階段檢查所需的程式庫和系統相依性是否可用，如果不可用，則會預設為使用 NIO。

要建置 ActiveMQ Artemis ASYNCIO 原生程式庫，請遵循這些說明。

3.6. 開放式 Web 應用程式安全專案 (OWASP) 報告

如果您想要產生相依性 CVE 的報告，您可以使用 -Powasp 設定檔進行建置，例如：

$ mvn -Powasp verify -DskipTests

每個子模組的輸出將位於 ./target/dependency-check-report.html 下。

4. 測試

4.1. 執行測試

要執行單元測試

$ mvn -Ptests test

從單元測試產生報告

$ mvn install site

個別執行測試

$ mvn -Ptests -DfailIfNoTests=false -Dtest=<test-name> test

其中 <test-name> 是測試類別的名稱，不包含其套件名稱。

4.2. 編寫測試

Broker 由 POJO 組成，因此很容易設定和執行 broker 執行個體，並測試特定功能。即使是涉及多個叢集 broker 的複雜測試案例也相對容易編寫。測試套件中的幾乎每個測試都遵循此模式 - 設定 broker、啟動 broker、測試功能、停止 broker。

測試套件使用 JUnit 來管理測試執行和生命週期。大多數測試都擴充 org.apache.activemq.artemis.tests.util.ActiveMQTestBase，其中包含 JUnit 設定和拆解方法，以及大量用於設定、啟動、管理和停止 broker 以及執行其他常見工作的公用程式函式。

請查看 org.apache.activemq.artemis.tests.integration.SimpleTest。這是一個非常簡單的測試案例，它擴充了 org.apache.activemq.artemis.tests.util.ActiveMQTestBase 並使用其方法來設定伺服器、執行測試，然後在測試完成後，super.tearDown() 會將其清除。測試案例包含註解以說明所有內容。顧名思義，這是一個簡單的測試案例，展示了測試套件最基本的功能。像這樣的簡單測試在現代硬體上執行不到一秒鐘。

儘管 org.apache.activemq.artemis.tests.integration.SimpleTest 很簡單，但透過擴充 org.apache.activemq.artemis.tests.util.SingleServerTestBase，可以使其更加簡單。此類別會自動完成簡單伺服器的所有設定，並向測試案例提供 ServerLocator、ClientSessionFactory 和 ClientSession 執行個體。 org.apache.activemq.artemis.tests.integration.SingleServerSimpleTest 是一個基於 org.apache.activemq.artemis.tests.integration.SimpleTest 的範例，但擴充了 org.apache.activemq.artemis.tests.util.SingleServerTestBase，這消除了由 SingleServerTestBase 本身提供的所有設定和類別變數。

4.3. 編寫 Web 測試

此 Broker 具有基於 hawtio 的 Web 控制台，並使用 smoke-tests 來測試它。例如，ConsoleTest 使用 selenium 框架檢查 Web 控制台。這些測試可以使用遠端伺服器、本機瀏覽器或 testcontainers 執行。若要使用遠端伺服器，請使用伺服器的 URL 設定 webdriver.remote.server 屬性，例如 -Dwebdriver.remote.server=https://#:4444/wd/hub。若要使用您的本機 Google Chrome 瀏覽器，請下載 Chrome 的 WebDriver 並使用 WebDriver 的路徑設定 webdriver.chrome.driver 屬性，例如 -Dwebdriver.chrome.driver=/home/artemis/chromedriver_linux64/chromedriver。若要使用您的本機 Firefox 瀏覽器，請下載 Firefox 的 WebDriver 並使用 WebDriver 的路徑設定 webdriver.gecko.driver 屬性，例如 -Dwebdriver.gecko.driver=/home/artemis/geckodriver-linux64/geckodriver。若要使用 testcontainers，請安裝 Docker。

4.4. 編寫良好測試的重點

4.4.1. 使用 logger.debug

  • 請使用 logger.debug 而不是 logger.info。

    在您的類別中，匯入以下內容

    public class MyTest {
private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger($CLASS_NAME$.class);

     @Test
     public void test() {
            log.debug("Log only what you need please!");
     }
}

  • 請勿使用 System.out.println()

一般而言，只有在您真的希望錯誤出現在報告中時才使用 System.out。偵錯資訊應該透過 logger.debug 呼叫。

4.4.2. 避免洩漏

任何測試案例的重要任務都是清理它在執行時建立的所有資源。這包括伺服器實例本身以及任何為了連線到伺服器而建立的資源（例如 ServerLocator、ClientSessionFactory、ClientSession 等的實例）。此任務通常在測試的 tearDown() 方法中完成。但是，ActiveMQTestBase（以及其他擴展它的類別）簡化了此過程。如 org.apache.activemq.artemis.tests.integration.SimpleTest 所示，當您建立測試時，可以使用幾種方法來確保在測試被拆解時 自動 進行適當的清理。這些包括

  • 所有重載的 org.apache.activemq.artemis.tests.util.ActiveMQTestBase.createServer(..) 方法。如果您選擇 不 使用這些方法之一來建立您的 ActiveMQServer 實例，則使用 addServer(ActiveMQServer) 方法將實例新增到測試套件的內部資源帳本中。

  • 來自 org.apache.activemq.artemis.tests.util.ActiveMQTestBase 的方法來建立 ServerLocator，例如 createInVMNonHALocator 和 createNettyNonHALocator。如果您選擇 不 使用這些方法之一，則使用 addServerLocator(ServerLocator) 將定位器新增到測試套件的內部資源帳本中。

  • org.apache.activemq.artemis.tests.util.ActiveMQTestBase.createSessionFactory(ServerLocator) 用於建立您的 Session Factory。如果您選擇 不 使用此方法，則使用 org.apache.activemq.artemis.tests.util.ActiveMQTestBase.addSessionFactory 將 Factory 新增到測試套件的內部資源帳本中。

4.4.3. 建立組態

在 org.apache.activemq.artemis.tests.util.ActiveMQTestBase 中，有很多方法可以用於建立組態。這些方法的命名方式類似於 create*Config(..)。每一個都會建立略有不同的組態，但它們之間有很多重疊之處。

無論如何，org.apache.activemq.artemis.core.config.Configuration 是一個 流暢 介面，因此很容易根據您的需要進行自訂。

4.4.4. 查看其他測試案例

如果您需要關於如何組態某個事物或測試某個事物的想法，請嘗試瀏覽測試套件，尋找其他可能類似的測試案例。這是學習測試套件如何運作以及如何利用測試基礎架構來測試您的特定案例的最佳方式之一。

5. 程式碼覆蓋率報告

5.1. 取得 JaCoCo exec 檔案

在您可以使用 JaCoCo 工具產生程式碼覆蓋率報告之前，您需要取得測試期間執行的程式碼行相關資料。這些資訊由 JaCoCo 代理程式收集並儲存在 JaCoCo exec 檔案中。您只需要使用 jacoco Maven 設定檔執行測試即可。

$ mvn test -Ptests,jacoco

5.2. 產生 JaCoCo 報告

$ mvn verify -Pjacoco-generate-report -DskipTests

為了產生 JaCoCo 報告，請僅使用設定檔 jacoco-generate-report 執行 Maven 建置，如上面的範例所示。在執行命令後，您可以在目錄 target/jacoco-report 中找到 HTML 和 XML 格式的報告。

5.3. 將 JaCoCo exec 檔案合併為一個

由於 ActiveMQ Artemis 被劃分為數個模組，因此會為每個模組分別產生 exec 檔案。如果您需要將它們合併在一起以將所有資料集中在一處，您可以使用下面的命令來完成。

$ mvn jacoco:merge -N -Pjacoco

6. 程式碼格式化

6.1. IDEA

如果您已完成 IDEA 指示中描述的步驟，並相應地選擇了程式碼樣式，您應該就可以開始使用了。

6.2. Eclipse

Eclipse 程式碼格式化和（基本）專案組態檔案位於 etc/ 資料夾中。您應該在 匯入所有專案 後手動複製它們

for settings_dir in `find . -type d -name .settings`; do
\cp -v etc/ide-settings/eclipse/org.eclipse.jdt.* $settings_dir
done

請勿使用 maven-eclipse-plugin 來複製檔案，因為它與 m2e 衝突。

6.3. EditorConfig

對於支援 EditorConfig 的編輯器，在 etc/ide-settings/editorconfig.ini 中提供了一個設定檔。將其複製到您的 Artemis 最上層目錄，並將 其命名為 .editorconfig

7. 驗證版本

7.1. 設定 Maven 儲存庫

當提出發佈時，會暫存一個 Maven 儲存庫。

此資訊擷取自 測試暫存版本的指南

例如，1.1.0 版本將 Maven 儲存庫暫存為 https://repository.apache.org/content/repositories/orgapacheactivemq-1066。

您需要做的第一件事是能夠使用此版本。我們發現最簡單的方法是在 ~/.m2/settings.xml 處變更您的 Maven 設定，設定暫存的儲存庫。

~/.m2/settings.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<settings>
   <profiles>
      <profile>
         <id>activemq-artemis-test</id>
         <repositories>
            <repository>
               <id>artemis-test</id>
               <name>ActiveMQ Artemis Test</name>
               <url>https://repository.apache.org/content/repositories/orgapacheactivemq-1066</url>
               <layout>default</layout>
               <releases>
                  <enabled>true</enabled>
               </releases>
               <snapshots>
                  <enabled>true</enabled>
               </snapshots>
            </repository>
         </repositories>

         <pluginRepositories>
            <pluginRepository>
               <id>artemis-test2</id>
               <name>ActiveMQ Artemis Test</name>
               <url>https://repository.apache.org/content/repositories/orgapacheactivemq-1066</url>
               <releases>
                  <enabled>true</enabled>
               </releases>
               <snapshots>
                  <enabled>true</enabled>
               </snapshots>
            </pluginRepository>
         </pluginRepositories>
      </profile>
   </profiles>

   <activeProfiles>
      <activeProfile>activemq-artemis-test</activeProfile>
   </activeProfiles>
</settings>

在您組態此設定之後，所有 Maven 物件都可用於您的建置。

7.2. 使用範例

Apache ActiveMQ Artemis 範例將建立伺服器並使用大多數 Maven 元件，如同真實的應用程式應該做的那樣。您可以在為暫存儲存庫安裝 .m2 設定檔後，執行這些範例來完成此操作。

當然，在您暫存 Maven 儲存庫後，您可以使用自己的應用程式。

8. 維護人員注意事項

ActiveMQ Artemis 提交者具有 Apache ActiveMQ Artemis 儲存庫的寫入權限，並將負責確認並推送透過 GitHub 上的提取請求提交的提交。

ActiveMQ Artemis 核心成員也可以直接將自己的提交推送到標準的 Apache 儲存庫。但是，此處的期望是開發人員已盡力測試他們的變更，並且相當有信心所提交的變更不會破壞建置。

相當有信心是什麼意思？如果開發人員已執行提取請求建置正在執行的相同 Maven 命令，他們可以相當有信心。目前，PR 建置執行此命令

$ mvn -Pfast-tests install

但是，如果變更是重大的、觸及廣泛的程式碼區域，或者即使開發人員只是想要第二意見，他們也會被鼓勵與社群的其他成員互動，以在推送之前獲得額外的審查。這可以透過 GitHub 上的提取請求、附加到電子郵件或 JIRA 的修補程式檔案、提交到 Apache Git 儲存庫中的分支等方式輕鬆完成。如果在提交到主要開發分支之前，有其他人查看重大變更，肯定會有所幫助，如果這有助於獲得「合理信心」，即建置沒有損壞且程式碼品質沒有下降。

如果建置確實損壞，則預期開發人員盡最大努力在合理的時間內修復建置。如果無法在合理的時間內修復，則可以還原提交並重新審查。

8.1. 使用開發設定檔

也鼓勵開發人員使用開發設定檔，這將在建置期間啟用 Checkstyle

$ mvn -Pdev install

8.2. 提交訊息

請確保提交訊息遵循 此處描述的 50/72 格式。此格式遵循官方 Git 書籍的建議。

8.3. 組態 Git 儲存庫

除了傳統的 origin 和 upstream 儲存庫之外，提交者還需要一個額外的參考，用於標準的 Apache Git 儲存庫，他們將在其中合併和推送提取請求。為了本文檔的目的，假設這些 ref/repo 關聯已如程式碼的使用部分所述存在

  • origin：https://github.com/(your-user-name)/activemq-artemis.git

  • upstream：https://github.com/apache/activemq-artemis

    1. 將標準的 Apache 儲存庫新增為遠端。這裡我們將其稱為 apache。

      $ git remote add apache https://gitbox.apache.org/repos/asf/activemq-artemis.git

    2. 將以下區段新增至您的 <artemis-repo>/.git/config 語句中，以擷取傳送到 GitHub 鏡像的所有提取請求。我們使用 upstream 作為遠端儲存庫名稱（如上所述），但如果您選擇不同的名稱，則遠端儲存庫名稱可能會不同。只需確保編輯所有對遠端儲存庫名稱的引用，使其保持一致即可。

       [remote "upstream"]
     url = git@github.com:apache/activemq-artemis.git
     fetch = +refs/heads/*:refs/remotes/upstream/*
     fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*

8.4. 合併和推送提取請求

以下是擷取 Pull Request、合併並將其推送到官方 Apache 儲存庫的基本指令。

  1. 下載所有遠端分支等，包括所有的 Pull Request。

    $ git fetch --all
Fetching origin
Fetching upstream
remote: Counting objects: 566, done.
remote: Compressing objects: 100% (188/188), done.
remote: Total 566 (delta 64), reused 17 (delta 17), pack-reused 351
Receiving objects: 100% (566/566), 300.67 KiB | 0 bytes/s, done.
Resolving deltas: 100% (78/78), done.
From github.com:apache/activemq-artemis
* [new ref]         refs/pull/105/head -> upstream/pr/105

  2. 檢出您希望審閱的 Pull Request。

    $ git checkout pr/105 -B 105

  3. 將分支變基到 main 分支之上，以便合併發生在目前 main 分支的頂端。

    $ git pull --rebase apache main

  4. 一旦您審閱了變更並準備合併，請檢出 main 分支。

    $ git checkout main

  5. 確保您的 main 分支也是最新的。

    $ git pull --rebase apache main

  6. 我們實際上建議再次檢出 main 分支，以確保您不會意外地加入任何額外的 commit。

    $ git fetch apache
$ git checkout apache/main -B main

  7. 從 Pull Request 建立一個新的合併 commit。重要：此處的 commit 訊息應該類似：「This closes #105」，其中「105」是 Pull Request 的 ID。「#105」會在 GitHub UI 中顯示為連結，可從 commit 訊息導覽到 PR。這將確保 GitHub Pull Request 即使由於最終變基而導致 commit ID 變更，仍然會關閉。

    $ git merge --no-ff 105 -m "This closes #105"

  8. 推送到官方 Apache 儲存庫。

    $ git push apache main

8.5. 使用自動化腳本

如果您遵循此處描述的命名慣例，您可以使用 scripts/rebase-PR.sh 腳本來自動化合併過程。這將執行先前章節中描述的確切步驟。

  • 只需使用

    $ <checkout-directory>/scripts/merge-pr.sh <PR number> Message on the PR

    範例

    $ pwd
/checkouts/apache-activemq-artemis

$ ./scripts/merge-PR.sh 175 ARTEMIS-229 address on Security Interface

    先前的範例取自一個真實案例，該案例生成了這個 在 #175 上的合併 commit。

  • 在此之後，您可以推送到官方 Apache 儲存庫。

    $ git push apache main

8.6. 為您的變更使用獨立分支

建議您不要在 main 分支上工作，原因有二

  1. 當您發送 PR 時，您的 PR 分支可能會在過程中被變基，並且您的 commit ID 會變更。當您變基舊分支時，可能會遇到意外的衝突。

  2. 您可能會最終推送您不打算推送的東西到上游。透過在遠離 main 分支的分支上工作來最小化您的風險。

8.7. 備註

GitHub 鏡像儲存庫（即 upstream）正在複製官方 Apache 儲存庫。因此，當 commit 被推送到 Apache 儲存庫時，與該 commit 反映在 GitHub 鏡像中之間可能會有輕微的延遲。當嘗試將 PR 推送到 apache 時，這可能會造成一些困難，因為該 PR 已合併到過時的 GitHub 鏡像中。您可以在鏡像更新之前執行上述步驟，或者您可以變更您本地的 main 分支，以追蹤官方 Apache 儲存庫上的 main 分支，而不是 GitHub 鏡像上的 main 分支。

$ git branch main -u apache/main

其中 apache 指向官方 Apache 儲存庫。

如果您希望您本地的 main 分支始終追蹤 upstream/main（即 GitHub 鏡像），那麼另一種實現此目的的方法是新增另一個追蹤 apache/main 的分支，並從該分支推送，例如：

$ git checkout main
$ git branch apache_main --track apache/main
$ git pull
$ git merge --no-ff pr/105
$ git push

9. 歷史

Apache ActiveMQ Artemis 專案於 2014 年 10 月啟動。Artemis 程式碼庫是透過 Red Hat 捐贈的 HornetQ 專案程式碼來啟動的。程式碼捐贈過程包括取得最新的 HornetQ 程式碼庫的快照，並將此快照作為 初始 git commit 貢獻到 Artemis git 儲存庫中。

HornetQ 的 commit 歷史被保留下來，可以在這裡存取：https://github.com/hornetq/hornetq/tree/apache-donation

應歸功於那些為 HornetQ 專案做出貢獻的開發人員。這裡重點介紹前 10 名的 commit 者

  • Clebert Suconic

  • Tim Fox

  • Francisco Borges

  • Andy Taylor

  • Jeff Mesnil

  • Ovidiu Feodorov

  • Howard Gao

  • Justin Bertram

  • Trustin Lee

  • Adrian Brock

如需更多資訊，請造訪 HornetQ GitHub 專案。

9.1. 變基原始捐贈

將捐贈歷史與 Artemis 歷史結合起來查看可能很有用。當最終查看舊的變更時，就是這種情況。

為此，有一個腳本會在 main/scripts 下針對捐贈分支變基 main 分支

  • rebase-donation.sh

已根據多個貢獻者授權協定授權給 Apache 軟體基金會（ASF）。有關著作權所有權的其他資訊，請參閱隨附此工作的 NOTICE 檔案。ASF 依據 Apache License, Version 2.0（「授權」）授權您使用此檔案；除非符合授權，否則您不得使用此檔案。您可以在以下位置取得授權的副本：

http://www.apache.org/licenses/LICENSE-2.0

除非適用法律要求或以書面同意，否則依據「現狀」基礎散佈的軟體，不附帶任何明示或暗示的擔保或條件。有關管轄權限和限制的特定語言，請參閱授權。