Hibernate OGM

贡献

GitHub 上的项目
问题跟踪器

Hibernate OGM 不再维护。

Hibernate OGM 是一个年轻的项目。代码、方向和文档都处于不断变化之中，由社区构建。加入我们，帮助我们塑造它！

如何获得帮助

首先，请确保您阅读了此参考文档。这是最全面的正式信息来源。当然，它并不完美：随时提出帮助请求、评论或建议在我们的 Hibernate OGM 论坛 中改进。

您还可以

  • 在 JIRA 中打开错误报告

  • 在 开发邮件列表 上提出改进建议

  • 加入我们到 IRC 中讨论开发和改进（#hibernate-dev 在 freenode.net 上；您需要在 freenode 上注册：该房间不接受“匿名”用户）。

如何贡献

欢迎！

有许多方法可以贡献

  • 在 JIRA 中报告错误

  • 在论坛、Zulip 或开发邮件列表中提供反馈

  • 改进文档

  • 修复错误或贡献新功能

  • 为您最喜欢的 NoSQL 引擎 提出并编写数据存储方言

Hibernate OGM 的代码可在 GitHub 上获得：https://github.com/hibernate/hibernate-ogm.

如何构建 Hibernate OGM

Hibernate OGM 使用 Git 和 Maven 3，请确保您的系统上已安装这两个工具。

从 GitHub 克隆 Git 仓库

git clone https://github.com/hibernate/hibernate-ogm
cd hibernate-ogm

运行 Maven

mvn clean install -s settings-example.xml

请注意，Hibernate OGM 使用来自 JBoss 托管的 Maven 仓库的工件。请确保使用 -s settings-example.xml 选项或根据 此 jboss.org wiki 页面 上的说明调整您的 ~/.m2/settings.xml 文件。

请注意，要针对单独安装的 MongoDB 和 CouchDB 服务器运行测试套件，必须通过环境变量指定其主机名。有关详细信息，请参阅下面的部分。

为了加快速度，您可以选择跳过部分构建过程。要运行最小的项目构建，不包括集成测试、文档和分发，请执行以下操作

mvn clean install -DskipITs -DskipDocs -DskipDistro -s settings-example.xml

以下部分将更详细地描述这些选项。

集成测试

默认情况下，集成测试将下载 WildFly 应用程序服务器，解压缩其中的模块，并使用 Arquillian 运行测试。您可以通过指定 skipITs 属性来跳过集成测试

mvn clean install -DskipITs -s settings-example.xml
MongoDB

为了在 mongodb 和 integrationtest/mongodb 模块中执行测试，使用 embedmongo-maven-plugin。它将下载 MongoDB 分发版，提取它，启动一个 mongod 进程，并在测试执行后关闭它。

如果需要，您可以配置 MongoDB 实例绑定到的端口（默认值为 27018）以及提取二进制文件的目标目录（默认为 ${project.build.directory}/embeddedMongoDb/extracted），如下所示

mvn clean install -s settings-example.xml -DembeddedMongoDbTempDir=<my-temp-dir> -DembeddedMongoDbPort=<my-port>

要使用单独安装的 MongoDB 实例，请指定 useExternalMongoDb 属性

mvn clean install -s settings-example.xml -DuseExternalMongoDb

这假设 MongoDB 安装在 localhost 上，使用默认端口且没有身份验证。如果您使用不同的设置，请在运行测试之前在 hibernate.properties 中配置所需的属性（对于 mongodb 中的测试）或在环境变量 MONGODB_HOSTNAME MONGODB_PORT MONGODB_USERNAME MONGODB_PASSWORD 中配置所需的属性（对于 integrationtest/mongodb 中的测试）。

export MONGODB_HOSTNAME=mongodb-machine
export MONGODB_PORT=1234
export MONGODB_USERNAME=someUsername
export MONGODB_PASSWORD=someP@ssw0rd
mvn clean install -s settings-example.xml
CouchDB

要运行 couchdb 模块中的测试，需要一个已安装的 CouchDB 服务器。在运行测试套件之前，通过设置环境变量 COUCHDB_HOSTNAME 指定其主机名

export COUCHDB_HOSTNAME=couchdb-machine

如果未设置此变量，则 couchdb 模块仍将被编译和打包，但测试将被跳过。

文档

默认情况下，文档将在项目构建过程中生成。您可以通过指定 skipDocs 属性来跳过它

mvn clean install -DskipDocs -s settings-example.xml

如果您只想构建文档，请从 documentation/manual 子目录运行它。

为了快速测试文档，您可以将生成的格式限制为 html 以加快速度

mvn clean install -f documentation/manual/pom.xml -s settings-example.xml -Djdocbook.format=html_single

分发

默认情况下，分发包将在项目构建过程中生成。您可以通过指定 skipDistro 属性来跳过它

mvn clean install -DskipDistro -s settings-example.xml

请务必查看源代码根目录中的 readme.md，以了解其他构建选项。

测试如何构建？

核心测试

核心中有两种类型的测试

  1. 核心本身的单元测试

  2. 以及“backendtck”，它是高层次（即 Session/EM 级）测试，并且针对所有后端执行。这是我们的后端 TCK。

要在 Eclipse 中针对特定存储运行特定测试，最简单的方法是使用 <StoreName>BackendTckHelper 类来运行测试。

例如，如果您想为 Neo4j 运行 BuiltInTypeTest 测试，请在您的 IDE 中打开 Neo4JBackendTckHelper 类，并将 @ClasspathSuite.ClassnameFilters 注释更改为

@ClasspathSuite.ClassnameFilters({ ".*BuiltInTypeTest" })

然后，只需在您的 IDE 中将 Neo4JBackendTckHelper 作为 JUnit 测试运行。

特定于方言的测试

对于特定于方言的单元测试，您只需在您的 IDE 中将测试作为 JUnit 测试运行。

代码组织

包的组织方式是在最低级别使用 SPI/impl 分割。SPI 面向网格方言实现者。这种分割尚未完成，因为“我们”的一些方言引用了核心中的“impl”类。任何不是“spi”或“impl”的都是公共 API。

如何有效地贡献代码

共享代码的最佳方式是在 GitHub 上为 Hibernate OGM 仓库创建分支，创建分支，并在准备就绪时打开拉取请求。在提供拉取请求之前，请确保将您的拉取请求重新绑定到 master 分支的最新版本。

以下是团队遵循的几种方法

  • 对于每个代码更改，我们进行小的独立提交。特别是，我们不会在同一个提交中混合样式代码更改（导入、拼写错误等）和新功能。

  • 提交消息遵循以下约定：JIRA 问题编号，简短的提交摘要，空行，如果需要，更长的描述。请确保将行长限制为 80 个字符，即使在今天，这也使得提交注释更易于阅读。

OGM-123 Summary of commit operation

Optional details on the commit
and a longer description can be
added here.

  • 拉取请求可以包含多个提交，但应该自包含：包括实现、单元测试、文档和必要时的 javadoc 更改。

  • 所有提交都将通过拉取请求进行提议，并在推送到参考仓库之前由团队的其他成员进行审查。没错，我们在没有代码审查的情况下从不直接提交到上游。

返回顶部