本黑客指南概述了开发人员如何参与 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 [email protected]:<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 push 会引用您要推送的分支，并默认使用 main，而不是您的工作分支。

  5. 讨论您计划的更改（如果您希望获得反馈）

  6. 完成代码功能/修复后，将您的分支重新设定到最新的 main 上（在 main 之上应用您的补丁）

    $ 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 将自动将您的本地提交（如果有）移动到您从其拉取的最新分支之上；如果您没有本地提交，则可以将其删除）。

    最后一个选项是，有些人更喜欢避免使用 pull，而只使用 fetch + rebase（当然，这需要更多输入）。例如

    $ git fetch upstream
$ git pull

  2. 将拉取的更新（或如果您未使用主题分支的本地提交）推送到您的私人 GitHub 仓库（origin）

    $ 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 [email protected]:<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 测试。在测试 -> 集成测试文件夹中选择任何测试类。右键单击项目选项卡中的类，然后单击“运行 <classname>”。如果“运行 <classname>”选项存在，那么您就可以开始使用了。

2.1.2. 关于 IBM JDK 在 IDEA 上的说明

如果您正在运行 IBM JDK，那么使其正常工作可能有点棘手。

将 JDK 添加到 IDE 后，还应将特定于您的平台的 vm.jar 添加到该 JDK 下（例如 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 中运行。

如果“运行 <classname>”或“运行所有测试”选项不存在，则可能是默认配置文件未正确导入。要在现有项目中（重新）导入“测试”Maven 配置文件，请执行以下操作

  • 打开 Maven 项目工具窗口：视图 -> 工具窗口 -> Maven 项目

  • 选择“配置文件”下拉菜单

  • 取消选中“测试”旁边的复选框，然后重新选中。

  • 单击窗口左上角的“重新导入所有 maven 项目”按钮。它看起来像一个圆形的蓝色箭头。

  • 等待 IDEA 重新加载，然后尝试再次运行 JUnit 测试。现在应该出现运行选项。

2.2. Eclipse

我们建议使用 Eclipse Kepler (4.3)，因为它内置了对 Maven 和 Git 的支持。请注意，一些子项目（例如文档）仍然使用一些在 Eclipse Kepler (4.3) 中不支持的 Maven 插件。

Eclipse m2e 已包含在“Eclipse IDE for Java Developers”中，或者可以从 Eclipse Kepler 发布仓库 中安装。

2.2.1. Git 设置

强烈建议关闭 Git Team 扩展的 .gitignore 文件自动更新功能。否则，它会在许多目录中生成新的 .gitignore 文件，这些文件由于顶层 .gitignore 文件的存在而变得多余。要关闭它，请转到 Preferences->Team->Git->Projects 并取消选中“自动忽略派生资源”复选框。

2.2.2. 架构设置

为了进行正确的架构验证，您可以将 Artemis 架构添加到您的 Eclipse XML 目录中。

  • 打开：Window -> Preferences -> XML -> XML Catalog

  • 选择添加 -> 工作区 -> 导航到 artemis-server 并选择 src/main/resources/schema/artemis-server.xsd -> 点击确定

  • 重复上述步骤并添加 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

  • 在“类型”下拉菜单中选择新建 ->“项目相对配置”

  • 为配置命名，并在位置下输入“/artemis-pom/etc/checkstyle.xml”，然后点击确定

  • 您现在应该在 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 Build Path -> Projects -> Add

  • 选择“unit-tests”项目，然后单击确定

现在，您应该能够运行测试，前提是您在前面的步骤中正确设置了注解预处理。

2.2.6. M2E Connector for Javacc-Maven-Plugin

Eclipse Indigo (3.7) 内置支持它。

在撰写本文时，Eclipse Kepler (4.3) 仍然缺乏对 Maven 的 javacc 插件的支持。可用的 m2e 连接器 for javacc-maven-plugin 需要降级 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 中创建 *太多* 项目，这会使您的 *Package Explorer* 和 *Project Explorer* 视图混乱。解决此问题的一种方法是使用 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. 编写测试

代理由 POJO 组成，因此配置和运行代理实例以及测试特定功能非常简单。即使是涉及多个集群代理的复杂测试用例也相对容易编写。测试套件中的几乎所有测试都遵循这种模式 - 配置代理、启动代理、测试功能、停止代理。

测试套件使用 JUnit 来管理测试执行和生命周期。大多数测试都扩展了 org.apache.activemq.artemis.tests.util.ActiveMQTestBase，其中包含 JUnit 设置和拆卸方法，以及大量实用程序函数，用于配置、启动、管理和停止代理，以及执行其他常见任务。

查看 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 测试

代理有一个基于 hawtio 的 Web 控制台，smoke-tests 用于测试它。例如，ConsoleTest 使用 selenium 框架 检查 Web 控制台。测试可以使用远程服务器、本地浏览器或 testcontainers 执行。要使用远程服务器，请使用服务器的 URL 设置 webdriver.remote.server 属性，例如 -Dwebdriver.remote.server=https://127.0.0.1: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)用于创建会话工厂。 如果您选择不使用此方法，那么请使用org.apache.activemq.artemis.tests.util.ActiveMQTestBase.addSessionFactory将工厂添加到测试套件的内部资源分类账中。

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 执行文件

在您使用 JaCoCo 工具生成代码覆盖率报告之前，您需要获取有关测试过程中执行了哪些代码行的数据。 这些信息由 JaCoCo 代理收集并存储在 JaCoCo 执行文件中。 您只需要使用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 执行文件合并为一个

由于 ActiveMQ Artemis 被分成多个模块，因此每个模块都会单独生成执行文件。 如果您需要将它们合并在一起以便将所有数据放在一个地方，您可以使用以下命令来完成。

$ 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. 使用 Dev 配置文件。

开发人员也鼓励使用 Dev 配置文件，它将在构建期间激活 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 = [email protected]:apache/activemq-artemis.git
     fetch = +refs/heads/*:refs/remotes/upstream/*
     fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*

8.4. 合并和推送拉取请求

以下是如何检索拉取请求、合并和将它们推送到规范的 Apache 仓库的基本命令。

  1. 下载所有远程分支等，包括所有拉取请求。

    $ 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. 签出您要审查的拉取请求

    $ git checkout pr/105 -B 105

  3. 将分支重新基线到主分支，这样合并将在当前主分支的顶部进行

    $ git pull --rebase apache main

  4. 一旦您审查了更改并准备合并，请签出main。

    $ git checkout main

  5. 确保您也更新了主分支。

    $ git pull --rebase apache main

  6. 我们实际上建议再次签出主分支，以确保您不会意外添加任何额外的提交

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

  7. 从拉取请求中创建一个新的合并提交。 重要：此处的提交信息应该类似于“这关闭了 #105”，其中“105”是拉取请求 ID。 “#105”在 GitHub UI 中显示为链接，用于从提交信息中导航到 PR。 这将确保即使提交 ID 由于最终的重新基线而发生更改，GitHub 拉取请求也会被关闭。

    $ 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 上的合并提交.

  • 之后，您可以推送到规范的 Apache 仓库。

    $ git push apache main

8.6. 为您的更改使用一个单独的分支

建议您远离主分支工作，原因有两个

  1. 当您发送 PR 时，您的 PR 分支可能会在过程中被重新基线，您的提交 ID 也会发生更改。 在重新基线旧分支时，您可能会遇到意外的冲突。

  2. 您最终可能会将您不想推送到上游的东西推送到上游。 通过在远离主分支的分支上工作来最大程度地降低风险。

8.7. 注意事项

GitHub 镜像仓库（即 upstream）正在克隆规范的 Apache 仓库。因此，Apache 仓库提交的代码与 GitHub 镜像仓库反映提交代码之间可能存在轻微的延迟。这可能会导致您在尝试将已在过时 GitHub 镜像上合并的 PR 推送到 apache 时遇到一些困难。您可以在执行上述步骤之前等待镜像更新，或者您可以将本地主分支更改为跟踪规范的 Apache 仓库上的主分支，而不是 GitHub 镜像上的主分支。

$ git branch main -u apache/main

其中 apache 指向规范的 Apache 仓库。

如果您希望您的本地主分支始终跟踪 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 代码库以红帽公司捐赠的 HornetQ 项目代码为基础。代码捐赠过程包括获取最新 HornetQ 代码库的快照，并将此快照作为 初始 git 提交 贡献到 Artemis git 仓库。

HornetQ 提交历史记录得以保留，您可以从此处访问：https://github.com/hornetq/hornetq/tree/apache-donation

应向为 HornetQ 项目做出贡献的开发人员表示感谢。以下是贡献最多的 10 位提交者

  • 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 重新设置在 main/scripts 下的捐赠分支的基础上

  • rebase-donation.sh

根据一个或多个贡献者许可协议授权 Apache 软件基金会 (ASF) 使用。有关版权所有权的更多信息，请参见随此作品分发的 NOTICE 文件。ASF 根据 Apache 许可证 2.0 版（“许可证”）向您授予此文件的许可；您不得在不遵守许可证的情况下使用此文件。您可以在以下地址获得许可证副本：

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

除非适用法律要求或书面同意，否则根据许可证分发的软件按“现状”分发，没有任何明示或暗示的保证或条件。请参阅许可证以了解管理权限和限制的特定语言。