Hibernate ORM 贡献指南从提交规范到持续集成的完整参与流程【免费下载链接】hibernate-ormIdiomatic persistence for Java and relational databases项目地址: https://gitcode.com/GitHub_Trending/hi/hibernate-ormHibernate ORM 是面向 Java 与关系数据库的持久化框架其社区贡献流程在 CONTRIBUTING.md 中有完整定义。本文以该文档为骨架结合仓库内的构建脚本、测试基础设施与维护文档系统讲解从法律合规、环境准备、分支与提交规范到 Pull Request 提交与 CI 校验的完整参与路径帮助你在提交第一行代码前就理解 Hibernate 社区的协作契约与质量门槛。为什么贡献规范如此重要开源项目的健康度依赖持续、有序的社区输入。Hibernate ORM 仓库的贡献规范核心解决三件事法律合规明确每一项贡献的许可归属与原创声明避免知识产权纠纷可追溯性通过 JIRA 议题号将每一次提交与缺陷、特性需求一一关联质量一致性通过统一的代码风格、测试要求与分类工具链保证大规模协作下代码仍可维护、可兼容。仓库中的 CONTRIBUTING.md 面向所有外部贡献者fork Pull Request 模式而 MAINTAINERS.md 面向拥有仓库直接推送权限的维护者两者在 CI 与发布环节相互衔接。法律与许可贡献前的三个约束Apache License 2.0 与双许可要求所有对 Hibernate 的原始贡献默认采用 Apache License 版本 2.0或修改文件自身指定的其他许可。仓库根目录的 LICENSE.txt 全文收录了 Apache-2.0 许可证文本。需要注意Hibernate ORM 7.0.0.Beta4 及更早版本采用不同的许可证分发。为了允许潜在的向后移植backporting社区要求贡献者对贡献进行双许可声明。仓库中的 .github/PULL_REQUEST_TEMPLATE.md 已经内置了标准措辞提交者确认其贡献在 Apache-2.0 条款下提交并可在未来由维护者酌情以 LGPL v2.1 条款重新许可。也就是说你提交 Pull Request 时模板会自动帮你完成这一法律声明无需额外操作。Developer Certificate of OriginDCO所有贡献均需遵守开发者原创证书DCO。DCO 1.1 全文存放在根目录的 dco.txt 中其核心主张是贡献者确认自己有权利提交该贡献、理解贡献公开且会被永久记录并随开源许可再分发。DCO 与 CLA贡献者许可协议的区别在于它不将版权转让给项目而是确认贡献者的原创与授权能力。版权所有者名单版权所有者列于 AUTHORS.txt。拥有合法版权主张的贡献者可以通过向项目的 GitHub 仓库提交 Pull Request、并在描述中列出至少一项相关贡献来申请加入该名单。需要注意一行式或重复性补丁通常不足以主张版权。该文件开头即注明列表并不穷尽还存在其他版权所有者并引导查看 CONTRIBUTING.md 了解加入方式。法律与法规合规所有贡献必须遵守适用法律法规包括美国出口管制与制裁限制。Hibernate 项目所属的 Linux 基金会对此发布了背景指引US OFAC Sanctions 相关指导这属于基金会层面的合规要求贡献者应知悉。贡献准则代码与文档各自的要求代码贡献的硬性要求贡献规范对代码提交提出了五条核心准则尊重项目代码风格提交前运行 spotless 与 checkstyle 检查例如./gradlew formatChecks。项目在 .idea 目录提供了 IntelliJ IDEA 的基础格式配置另有面向 IDEA 与 Eclipse 的通用指南可供参考。对应 JIRA 议题在 Hibernate JIRAHHH 项目 创建或关联议题并在提交信息中包含该议题的 key。配套测试仓库提供了一套测试模板供参考。提交缺陷修复时测试应复现原始缺陷并证明修复有效提交特性增强时测试应演示特性按预期工作。两种情况都必须把测试合入项目防止将来回归。更新文档如果改动涉及用户可见行为应同步更新文档。构建与测试通过代码必须编译且测试通过./gradlew clean build。此外凡是新增、暴露、重新分类、移动或不兼容地修改 API、SPI 或内部契约的改动必须遵循 Classification Tooling Guide——这是 Hibernate 维持兼容性承诺的关键机制详见下文兼容性分类工具链一节。代码风格在构建层的具体落地CONTRIBUTING.md 提到的formatChecks并非抽象要求它在 local-build-plugins/src/main/groovy/local.code-quality.gradle 中有明确的实现formatChecks任务聚合了spotlessCheck与enforceRules只做静态检查、无需编译用于 CI 环境spotless 配置对 Java 源码执行替换许可证文件头来自 shared/config/spotless/license.java、移除未使用的 import、将 4 空格前导缩进转为 TAB、去除行尾空白、保证文件以换行结尾。值得注意的是 spotless 在此项目中的定位是自动修复错误而非直接判失败enforceCheck false并且compileJava会依赖spotlessJavaApply即编译前自动格式化enforceRules是一个自定义正则规则检查器扫描src/main/java下的文件并检查禁止sun/java.awt/org.slf4j的非法 import、}后缺少换行的else/catch/finally、小写l长整型字面量如1l、以及equals/hashCode不成对实现等问题违反即抛GradleException。这解释了为什么 .idea/codeStyles/Project.xml 中大量使用了换行{、括号内空格、强制花括号等风格选项并设置USE_TAB_CHARACTER为 true——与 spotless 的 TAB 缩进策略完全一致。文档贡献的要求文档贡献主要尊重项目代码风格尤其是TAB 的使用上述 IDEA/Eclipse 风格模板同样适用。理想情况下文档贡献也应关联 JIRA 议题但相对代码贡献来说这不是必需项。开始之前环境与前置准备如果你是第一次通过 Git/GitHub 参与 Hibernate请依次完成注册 Hibernate JIRA 账户hibernate.atlassian.net 的 HHH 项目用于创建与跟踪议题注册 GitHub 账户Fork 仓库并完成本地 Git 配置、clone 你的 fork配置git blame忽略文件在本地 clone 目录下执行git config blame.ignoreRevsFile .git-blame-ignore-revs仓库根目录的 .git-blame-ignore-revs 收录了一批纯格式化/大文件移动的提交哈希例如启用 spotless 自动格式化的初始提交、Envers 移除恢复、Hibernate Tools 合并相关提交。配置后git blame会自动跳过这些噪音提交让你看到真正有意义的代码演进历史配置 IDE参照 wiki 上的 IntelliJ IDEA 或 Eclipse 设置指南。关于 IDE 导入的一个注意点CONTRIBUTING.md 在脚注中特别提醒Gradle 的eclipse插件已不再受支持推荐使用 IDE 自身的工具/插件导入项目。不要再尝试在命令行运行./gradlew clean eclipse --refresh-dependencies会因eclipse任务不存在而报错。创建工作topic分支Hibernate 采用主题分支工作流。约定将 JIRA 议题 key 融入分支名——虽然这更多是记忆策略而非硬性规则但它能帮助你记住每个分支的用途将当前工作与其他贡献隔离。如果尚不存在覆盖你工作的 JIRA 议题请先创建一个。例如假设从main分支出发、处理 JIRA 议题 HHH-123git checkout -b HHH-123 main编码、提交与合入上游编码Do your thing!——在主题分支上自由实现你的改动但受前述准则约束风格合规、测试配套、文档同步。提交规范逻辑单元提交每次提交应是一个自洽的逻辑单元以 JIRA 议题 key 开头每条提交信息必须以 JIRA 议题 key 开头如HHH-123: ...这是 JIRA 自动关联提交并展示在议题页面的机制包含必要测试确认已为改动添加测试运行全部测试确保没有意外破坏其他功能。在提交前合并上游最新改动时规范强烈建议使用rebase 而非 merge——merge 会产生merge commits搅乱项目时间线。提交 Pull Request将改动推送到你 fork 的主题分支发起 Pull Request提交后可以验证 PR 与 JIRA 议题是否正确关联议题状态应变为Waiting for Review点击议题右侧Recent rule runs区域的Refresh按钮后应出现一条Pull Request (ORM)记录。主题分支本身需要遵守两条约束隔离性分支只包含这一个 JIRA 议题或多个相关联且一并修复的议题的工作不要把多个 PR 的提交推到同一分支——GitHub 的 PR 绑定的是分支而非具体提交存续期分支应保留到 PR 关闭为止。一旦底层分支被删除对应 PR 也会被关闭改动将丢失。许可声明的自动落位正如前面所述.github/PULL_REQUEST_TEMPLATE.md 在 PR 描述模板中内置了 Apache-2.0 LGPL v2.1 双许可确认文案首次贡献者还会被引导去阅读 CONTRIBUTING.md因此贡献者在提交流程中不会遗漏法律声明。兼容性分类工具链API/SPI/内部契约的守护代码贡献准则中涉及 API/SPI/内部契约改动必须遵循 Classification Tooling Guide这一条指向的是 Hibernate 自研的分类工具链。该指南定义了三种互斥分类API面向应用程序的受支持契约供普通应用使用SPI面向独立于 Hibernate ORM 发布的服务提供方的契约InternalHibernate 实现细节对应用和提供方都不做兼容性承诺。分类模型由编译产物经聚合 Jandex 索引推导出classifications.json再衍生出人类可读报告、分类校验、SPI 角色与形态校验、提供方边界校验以及 API/SPI 迁移兼容性校验。SPI 声明可附带独立角色USE可命名并使用、IMPLEMENT可实现/扩展/覆写、SUPPLY可通过文档化供给点提供实现或值三者相互独立、按需声明。对贡献者的实际含义是如果你的改动触及对外契约提交前应运行分类校验相关任务确保新声明被正确归类例如进入spi或internal包以遵循包级默认约定并保证不破坏迁移兼容性分析。维护者则负责在 CI 中选择兼容性基线与启用显式兼容性检查详见 MAINTAINERS.md。测试基础设施贡献测试可以借助什么CONTRIBUTING.md 要求一套合适的测试并提及官方测试模板。在仓库内部hibernate-testing 模块hibernate-testing/src/main/java/org/hibernate/testing提供了丰富的测试支持类型包括方言/环境条件注解RequiresDialect、RequiresDialects、RequiresDialectFeature、SkipForDialect、SkipForDialects、DialectCheck/DialectChecks用于按数据库方言裁剪测试生命周期与期望失败机制BeforeClassOnce、AfterClassOnce、FailureExpected、OnExpectedFailure、OnFailure、Skip等辅助设施JTA、JDBC、bytecode、bytebuddybyteman、cache、cleaner、schema、transaction 等按用途分包的测试工具。这些工具与主模块的 8000 测试类共同构成回归防线。贡献测试时参考这些注解与工具能让你的测试在 Hibernate 的方言矩阵MySQL、PostgreSQL、Oracle、DB2、SQL Server 等下正确运行或按预期跳过。持续集成与发布贡献进入主线的最后一公里CONTRIBUTING.md 将 CI 与发布细节指向 MAINTAINERS.md。从维护者视角Hibernate 的 CI 分布在两套平台GitHub Actions 工作流位于 .github/workflows例如 ci.yml自托管 Jenkins 实例主流水线定义在根目录 Jenkinsfile负责为主分支构建与 PR 构建测试更多数据库方言发布流水线定义在 ci/release/Jenkinsfile。CI 构建会执行ciCheck依赖check期间按 local.code-quality.gradle 的配置禁用spotlessApply等自动修复任务只保留检查语义确保 CI 上验证的就是真实提交的代码状态。此外构建还集成了 forbidden-apis签名来自 rules/forbidden-apis.txt默认启用jdk-system-out与jdk-non-portable检查并允许通过AllowSysOut等注解豁免以及可选的 Error Prone/NullAway 静态分析。发布方面维护分支如6.2、6.4、7.0在周末存在自动化 micro 版本发布机制触发条件是自上次发布以来存在以[HHH-或HHH-开头的提交信息——这再次印证了提交信息以 JIRA key 开头这一规范在整个发布链路中的关键作用它不仅是可追溯性要求更是自动化发布判定的直接依据。小结贡献 Hibernate 的完整清单阶段关键动作依据文件法律合规接受 Apache-2.0 LGPL v2.1 双许可、DCO 声明LICENSE.txt、dco.txt、.github/PULL_REQUEST_TEMPLATE.md议题跟踪创建/关联 HHH JIRA 议题分支与提交均使用议题 keyCONTRIBUTING.md环境准备fork、配置git blame忽略文件、按风格模板配置 IDE.git-blame-ignore-revs、.idea分支git checkout -b HHH-123 mainCONTRIBUTING.md编码./gradlew formatChecks通过契约改动过分类校验local.code-quality.gradle、classification-tooling.adoc测试配套测试并入项目防回归可复用 hibernate-testing 基础设施hibernate-testing/src/main/java/org/hibernate/testing提交逻辑单元、JIRA key 开头、rebase 而非 mergeCONTRIBUTING.mdPR推送主题分支、发起 PR、核对 JIRA 关联状态.github/PULL_REQUEST_TEMPLATE.mdCI/发布由维护者通过 Jenkins/GitHub Actions 把关Jenkinsfile、ci/release/Jenkinsfile、MAINTAINERS.md遵循这份流程你的贡献就能在 Hibernate 的可追溯议题链、统一代码风格、完整测试与兼容性校验的共同护航下顺利汇入这个被广泛应用于企业级 Java 项目的持久化框架。【免费下载链接】hibernate-ormIdiomatic persistence for Java and relational databases项目地址: https://gitcode.com/GitHub_Trending/hi/hibernate-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考