Marquez项目开发指南：从代码规范到贡献流程详解

Marquez项目开发指南：从代码规范到贡献流程详解

项目概述

Marquez是一个开源的数据血缘追踪系统，它帮助组织理解数据如何在系统中流动和转换。作为数据治理的关键组件，Marquez提供了数据来源、转换和依赖关系的可视化展示。

开发环境搭建

测试运行指南

Marquez使用Gradle作为构建工具，测试套件分为多个类别：

1. 完整测试套件执行命令：

./gradlew test

2. 模块化测试支持针对特定子模块运行测试：

./gradlew :api:test --tests marquez.api.OpenLineageResourceTest

3. 分类测试支持按测试类型执行：

./gradlew :api:testUnit        # 单元测试
./gradlew :api:testIntegration # 集成测试
./gradlew :api:testDataAccess  # 数据访问测试

代码格式化规范

项目采用Spotless工具强制执行Google Java代码风格规范。提交前必须运行：

./gradlew spotlessApply

开发建议：

• 安装Google Java Format插件到IDE
• 推荐安装Lombok插件以支持项目中的Lombok注解

Git工作流最佳实践

预提交钩子配置

项目使用pre-commit管理Git钩子，配置步骤：

1. 安装pre-commit工具
2. 初始化Git钩子脚本：

pre-commit install

分支命名规范

采用分组前缀+描述性名称的命名方式：

• feature/：新功能开发
• bug/：问题修复
• improvement/：改进建议

示例：

feature/data-lineage-visualization
bug/fix-null-pointer-exception

持续集成与本地验证

项目使用GitHub Actions进行CI验证，开发者可使用act工具在本地模拟CI流程：

1. 安装act工具
2. 创建配置文件.actrc指定运行环境
3. 执行验证：

act pull_request --reuse --verbose

常见问题：当kind集群删除失败时，手动执行：

kind delete clusters chart-testing

代码提交规范

签名要求

所有提交必须包含开发者签名，确认贡献者权利：

git commit -s -m "提交信息描述"

版权声明规范

所有源文件必须包含SPDX标准的版权声明：

Java文件：

/*
 * Copyright 2018-2022 contributors to the Marquez project
 * SPDX-License-Identifier: Apache-2.0
 */

Shell脚本：

#!/bin/bash
#
# Copyright 2018-2022 contributors to the Marquez project
 * SPDX-License-Identifier: Apache-2.0

API文档管理

项目使用OpenAPI规范描述API，文档生成工具链：

1. 安装redoc-cli工具
2. 生成静态文档：

redoc-cli bundle spec/openapi.yml -o docs/openapi.html

3. 本地预览：

redoc-cli serve spec/openapi.yml

依赖管理策略

项目采用renovate自动化管理大多数依赖，例外情况包括：

• Web相关代码依赖
• Spark版本（因OpenLineage集成稳定性考虑）
• Gradle构建工具（核心构建流程稳定性考虑）

贡献流程详解

1. 创建功能分支
2. 实现变更并编写测试
3. 验证代码格式和版权声明
4. 签名提交
5. 创建合并请求
6. 与维护者协作完成代码审查

关键要求：

• 每个变更必须附带测试
• 提交信息格式规范
• 保持变更范围小而集中
• 问题修复需关联对应issue

开发建议

1. 单一提交原则：使用git commit --amend或交互式rebase保持一个功能一个提交
2. 测试驱动：先编写测试再实现功能
3. 模块化思维：保持变更范围聚焦特定模块
4. 文档同步：API变更需同步更新OpenAPI规范

通过遵循这些规范和实践，开发者可以高效地为Marquez项目做出贡献，同时保持代码库的一致性和可维护性。