尧图网站建设 
Lance 项目贡献指南从 Conventional Commits 到格式规范投票的完整参与路径【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance本指南系统讲解 Lance 开源项目面向多模态 AI 的开源湖仓格式核心仓库托管于 lance-format 组织的完整贡献流程以 Conventional Commits 规范提交代码、通过 GitHub Discussion 与 Draft PR 推进功能设计、在 CI 结构化门禁下完成格式规范protobuf 定义与格式文档的 PMC 投票以及如何参与 AI 工具链的持续改进。读完本文你将掌握从提交第一个 PR 到推动一项格式规范变更所需的全部规则、工具链与投票机制。贡献总览PR 评审与权限模型Lance 的代码贡献以 GitHub Pull RequestPR为主要形式所有 PR 都需要拥有写权限的维护者Maintainer评审与批准后方可合并。围绕这一核心流程Lance 社区治理文档docs/src/community/index.md定义了三级参与结构贡献指南针对不同层级的参与者给出了相应要求Contributor贡献者任何为 Lance 做出贡献的人贡献形式不限于代码——报告 bug、提出功能请求、参与评审、写作文档、组织活动等均算贡献Maintainer维护者长期持续贡献并获得认可的贡献者拥有合并 PR 等写权限PMC项目管理委员会展现领导力的维护者负责项目长期方向与治理决策成员名册见 docs/src/community/pmc.yaml详细职责见 docs/src/community/pmc.md。贡献指南明确区分了两类变更的审批路径普通代码变更由维护者评审批准涉及 Lance 格式规范protobuf 定义与格式文档的变更则需要 PMC 投票。下文分别展开。Conventional Commits提交信息的硬性规范Lance 各项目统一采用 Conventional Commits 标准编写提交信息。这一标准让提交历史能清晰区分破坏性变更与非破坏性变更通过在提交类型后加!如feat!: ...或使用BREAKING CHANGE:页脚来标记破坏性变更变更类型feat:新功能、fix:缺陷修复、docs:文档更新以及其他类型。这一标准并非可有可无的风格偏好而是被自动化工具直接消费的事实来源。仓库中的 ci/generate_release_notes.py 会在每次发布时比较两个 git tag 之间的提交从中提取 PR 编号、按标签分类并自动生成 release notesci/check_breaking_changes.py 则检查 base 与 head 之间的所有 PR 是否带有breaking-change标签若存在破坏性变更但 minor 版本号未递增CI 将直接失败。此外AGENTS.md 明确要求 PR 标题必须遵循 Conventional Commits 规范因为.github/workflows/pr-title.yml会用 commitlint 校验 PR 标题与正文合法前缀包括feat:、fix:、docs:、perf:、ci:、test:、build:、style:、chore:并可附带 scope。需要关注的两个重要标签仓库根目录的 CONTRIBUTING.md 补充了两个对发布流程至关重要的 PR/Issue 标签breaking-change任何引入公开 APIRust 或 Python破坏性变更的 PR 必须打上此标签它决定了发布时版本号如何递增。即使 PR 已合并也可以补加。critical-fix修复关键 bug安全漏洞、数据损坏、崩溃等用户可能未察觉的问题的 PR 应打此标签用于判断是否需要发布补丁版本。Feature Design Proposals功能设计的协作流程Lance 的设计随社区输入与共识自然演进重大技术变更通过以下有机流程讨论而非依赖强制性的设计文档模板发起 Discussion在 GitHub Discussions 中发布设计提案收集社区反馈利用讨论串探索不同方面与备选方案迭代设计与社区互动根据反馈与专业意见持续打磨方案通过 Draft PR 落实细节当大方向获得社区认可后发布 Draft PR 帮助敲定实现细节——Draft PR 被明确鼓励因为它能促进具体、可落地的讨论拆分变更将大型 Draft PR 拆分为更小、可增量合入的 PR便于评审并持续展示进展正式投票拥有写权限的维护者可批准与设计相关的代码修改若设计涉及 Lance 格式规范变更则变更走独立 PR由 PMC 依据投票要求进行投票。这一流程与 docs/src/community/index.md 中描述的Subproject子项目治理相互呼应孵化中的子项目Incubating Subproject可通过 PMC 投票晋级为正式子项目晋级条件包括完整的 CI/issue 跟踪/贡献指南、代码标准执行、已确立的使用场景、核心贡献者之外的社区采用以及至少一位 Lance 维护者积极维护。Format Specification Changes格式规范变更的投票机制Lance 格式规范——protobuf 定义与 docs/src/format/ 目录下的规范文档——的变更是最特殊的一类贡献PR 本身就是提案PMC 直接在 PR 上投票无需先开讨论串或写独立设计文档。这一要求不是靠约定维持而是在 CI 中结构化强制执行的。提案范围控制格式规范 PR 应严格限定在规范本身protobuf 定义与规范文档外加维持构建通过所需的最小库改动例如同步重命名的生成字段。行为的实现应放在后续 PR 中。这不仅是整洁偏好——投票针对的是格式本身这是一份比任何单一实现都更持久的兼容性契约PMC 成员应当能完整阅读他们投票的对象。一个同时携带 reader、writer 与测试变更的 PR 会把契约淹没在实现细节里也让一次普通代码评审被迫经历本不需要的 72 小时投票期。讨论以 PR 评审意见的形式进行评审者可以针对规范的具体行进行回复PR 成形期间保持 Draft 状态标记 ready for review 时投票期才开始。投票门Format Vote Gate的执行细节投票的执行逻辑完整实现在 ci/format_vote_gate.py 中其模块文档与投票机制文档docs/src/community/voting.md完全对应。关键机制如下如何被识别为格式变更当 PR 修改了protos/**/*.proto或docs/src/format/**时会被路径标签器自动打上format-change标签。路径分类逻辑在.github/labeler-area.yml中配置并由 ci/test_labeler_area.py 做回归测试确保A-format与format-change使用完全相同的路径集合且只有持久化的 protos 算格式变更执行类 proto 如protos/ann.proto等被排除在外。阻塞合并的三个条件由format-spec-vote状态检查强制执行条件要求实现要点三个绑定 1 票3 位 PMC 成员批准 PR提案人除外只有最新 commit 上的批准有效——推送新 commit 会使旧批准失效tally_reviews中按commit_id head_sha判定无否决票无 PMC 成员持有未解决的 Request changes 评审请求变更即 −1 绑定票视为否决veto直到撤回前一直阻塞合并最短投票期距投票开启至少 72 小时周末不计入 72 小时投票期在 PR 同时具备format-change标签且退出 Draft 后开启取两者较晚者从源码可以看到更多细节每位评审者只统计其最近一次立场评审_STANCE_STATES仅包含 APPROVED / CHANGES_REQUESTED / DISMISSEDCOMMENTED 与 PENDING 被忽略PR 作者即使身为 PMC 也永远不计入周末边界固定在 UTCWEEKEND_TZ timezone.utc避免 DST 与时区争议而截止时间在注释中以 UTC 和太平洋时间双时区显示。PMC 名册从 docs/src/community/pmc.yaml 读取每 15 分钟重新评估一次因此统计注释与状态检查会比评审滞后几分钟。判定优先级decide_verdict依次为否决票 批准数不足 投票期未满 通过。对于不改变格式的琐碎编辑错别字、措辞、格式调整PMC 成员可打format-waived标签免除投票。投票期的纯函数逻辑投票开启时刻与截止时刻的计算被刻意实现为纯函数vote_opened_at、weekday_deadline并由 ci/test_format_vote_gate.py 以参数化测试全面覆盖运行方式为pytest ci/test_format_vote_gate.py。测试用例清晰地展示了周末排除规则的实际效果周一 09:00 开启截止为周四 09:00整 72 小时偏移周五 17:00 开启周六前累积 7 小时剩余 65 小时从下周一 00:00 继续最终落在周三 17:00——周五下午的提案仍能获得三个完整工作日周末期间开启时钟从周一才开始计跨多个周末的长投票期会跳过不止一个周末如 6 天时长实际截止在下一个周一。AI Tooling Integrations持续改进 AI 工具链Lance 社区鼓励贡献者持续改进与 AI 工具的集成具体包括三个方面增强编码 Agent 指南如根目录及各子项目下的AGENTS.md、CLAUDE.md本仓库可见 AGENTS.md、rust/AGENTS.md、python/AGENTS.md、java/AGENTS.md、protos/AGENTS.md、docs/src/format/AGENTS.md向 AI 代码评审者提供反馈帮助改进 AI 辅助评审的质量开发与改进 AI 驱动的 GitHub Actions如自动打标签、自动投票门等工作流。这些指南文件本身就是高度工程化的例如 AGENTS.md 详细规定了开发命令cargo check --workspace --tests --benches、cargo clippy --all --tests --benches -- -D warnings、cargo fmt --all、编码标准Rust/Python/Java 绑定保持薄封装、永不破坏公开 API 签名、用indices而非indexes、测试标准没有测试的代码不合并、向量索引测试必须断言 recall 指标不低于 0.5、跳过测试必须关联 GitHub issue以及 PR 提交前的 lint 检查要求。项目专属贡献指南CONTRIBUTING.md 与实战建议每个项目在各自的CONTRIBUTING.md中维护详细的贡献指南。以仓库根目录的 CONTRIBUTING.md 为例它为新贡献者提供了从零开始的完整路径环境准备安装 Rust、Python 3.10、protobuf3.20 及以上版本、pre-commit 并运行pre-commit install示例工作流Fork 仓库 → 选择 issue → 创建分支 → 修改 → 从 fork 发起 PR → 反馈迭代 → 合并评审标准Rust 公开 API 优先使用 builder 模式或 options struct 而非长参数列表输入优先使用IntoT/AsRefT提升灵活性所有新公开 API 必须有文档与示例所有 bugfix 与功能必须有对应测试运行基准测试Rust 基准测试每日多次运行向量索引基准针对 sift1m 数据集另有 tpch 基准均位于benchmarks/目录。结合 AGENTS.md 的补充建议提交 PR 前的自查清单可以归纳为运行全部受影响语言面的 lint 检查Rust 侧cargo fmt --all与cargo clippy --all --tests --benches -- -D warningsPython 侧从python/目录执行uv run make lintPR 标题遵循 Conventional Commits破坏性变更打breaking-change标签关键修复打critical-fix标签若触碰格式规范路径则等待format-spec-vote门禁通过。总结Lance 的贡献体系可以概括为一条主线与两条支线主线是所有代码贡献通过 PR 提交并接受维护者评审两条支线分别是面向重大功能设计的 Discussion Draft PR 迭代流程以及面向格式规范变更的PR 即提案、PMC 结构化投票机制。对于贡献者而言理解 Conventional Commits 是融入提交历史的基础理解投票门的三个条件三票、无否决、72 小时则是推动格式演进的关键。相关文档与实现均可在仓库中继续深入研读docs/src/community/contributing.md、docs/src/community/voting.md、ci/format_vote_gate.py、ci/test_format_vote_gate.py。【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Lance 项目贡献指南：从 Conventional Commits 到格式规范投票的完整参与路径
Lance 项目贡献指南从 Conventional Commits 到格式规范投票的完整参与路径【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance本指南系统讲解 Lance 开源项目面向多模态 AI 的开源湖仓格式核心仓库托管于 lance-format 组织的完整贡献流程以 Conventional Commits 规范提交代码、通过 GitHub Discussion 与 Draft PR 推进功能设计、在 CI 结构化门禁下完成格式规范protobuf 定义与格式文档的 PMC 投票以及如何参与 AI 工具链的持续改进。读完本文你将掌握从提交第一个 PR 到推动一项格式规范变更所需的全部规则、工具链与投票机制。贡献总览PR 评审与权限模型Lance 的代码贡献以 GitHub Pull RequestPR为主要形式所有 PR 都需要拥有写权限的维护者Maintainer评审与批准后方可合并。围绕这一核心流程Lance 社区治理文档docs/src/community/index.md定义了三级参与结构贡献指南针对不同层级的参与者给出了相应要求Contributor贡献者任何为 Lance 做出贡献的人贡献形式不限于代码——报告 bug、提出功能请求、参与评审、写作文档、组织活动等均算贡献Maintainer维护者长期持续贡献并获得认可的贡献者拥有合并 PR 等写权限PMC项目管理委员会展现领导力的维护者负责项目长期方向与治理决策成员名册见 docs/src/community/pmc.yaml详细职责见 docs/src/community/pmc.md。贡献指南明确区分了两类变更的审批路径普通代码变更由维护者评审批准涉及 Lance 格式规范protobuf 定义与格式文档的变更则需要 PMC 投票。下文分别展开。Conventional Commits提交信息的硬性规范Lance 各项目统一采用 Conventional Commits 标准编写提交信息。这一标准让提交历史能清晰区分破坏性变更与非破坏性变更通过在提交类型后加!如feat!: ...或使用BREAKING CHANGE:页脚来标记破坏性变更变更类型feat:新功能、fix:缺陷修复、docs:文档更新以及其他类型。这一标准并非可有可无的风格偏好而是被自动化工具直接消费的事实来源。仓库中的 ci/generate_release_notes.py 会在每次发布时比较两个 git tag 之间的提交从中提取 PR 编号、按标签分类并自动生成 release notesci/check_breaking_changes.py 则检查 base 与 head 之间的所有 PR 是否带有breaking-change标签若存在破坏性变更但 minor 版本号未递增CI 将直接失败。此外AGENTS.md 明确要求 PR 标题必须遵循 Conventional Commits 规范因为.github/workflows/pr-title.yml会用 commitlint 校验 PR 标题与正文合法前缀包括feat:、fix:、docs:、perf:、ci:、test:、build:、style:、chore:并可附带 scope。需要关注的两个重要标签仓库根目录的 CONTRIBUTING.md 补充了两个对发布流程至关重要的 PR/Issue 标签breaking-change任何引入公开 APIRust 或 Python破坏性变更的 PR 必须打上此标签它决定了发布时版本号如何递增。即使 PR 已合并也可以补加。critical-fix修复关键 bug安全漏洞、数据损坏、崩溃等用户可能未察觉的问题的 PR 应打此标签用于判断是否需要发布补丁版本。Feature Design Proposals功能设计的协作流程Lance 的设计随社区输入与共识自然演进重大技术变更通过以下有机流程讨论而非依赖强制性的设计文档模板发起 Discussion在 GitHub Discussions 中发布设计提案收集社区反馈利用讨论串探索不同方面与备选方案迭代设计与社区互动根据反馈与专业意见持续打磨方案通过 Draft PR 落实细节当大方向获得社区认可后发布 Draft PR 帮助敲定实现细节——Draft PR 被明确鼓励因为它能促进具体、可落地的讨论拆分变更将大型 Draft PR 拆分为更小、可增量合入的 PR便于评审并持续展示进展正式投票拥有写权限的维护者可批准与设计相关的代码修改若设计涉及 Lance 格式规范变更则变更走独立 PR由 PMC 依据投票要求进行投票。这一流程与 docs/src/community/index.md 中描述的Subproject子项目治理相互呼应孵化中的子项目Incubating Subproject可通过 PMC 投票晋级为正式子项目晋级条件包括完整的 CI/issue 跟踪/贡献指南、代码标准执行、已确立的使用场景、核心贡献者之外的社区采用以及至少一位 Lance 维护者积极维护。Format Specification Changes格式规范变更的投票机制Lance 格式规范——protobuf 定义与 docs/src/format/ 目录下的规范文档——的变更是最特殊的一类贡献PR 本身就是提案PMC 直接在 PR 上投票无需先开讨论串或写独立设计文档。这一要求不是靠约定维持而是在 CI 中结构化强制执行的。提案范围控制格式规范 PR 应严格限定在规范本身protobuf 定义与规范文档外加维持构建通过所需的最小库改动例如同步重命名的生成字段。行为的实现应放在后续 PR 中。这不仅是整洁偏好——投票针对的是格式本身这是一份比任何单一实现都更持久的兼容性契约PMC 成员应当能完整阅读他们投票的对象。一个同时携带 reader、writer 与测试变更的 PR 会把契约淹没在实现细节里也让一次普通代码评审被迫经历本不需要的 72 小时投票期。讨论以 PR 评审意见的形式进行评审者可以针对规范的具体行进行回复PR 成形期间保持 Draft 状态标记 ready for review 时投票期才开始。投票门Format Vote Gate的执行细节投票的执行逻辑完整实现在 ci/format_vote_gate.py 中其模块文档与投票机制文档docs/src/community/voting.md完全对应。关键机制如下如何被识别为格式变更当 PR 修改了protos/**/*.proto或docs/src/format/**时会被路径标签器自动打上format-change标签。路径分类逻辑在.github/labeler-area.yml中配置并由 ci/test_labeler_area.py 做回归测试确保A-format与format-change使用完全相同的路径集合且只有持久化的 protos 算格式变更执行类 proto 如protos/ann.proto等被排除在外。阻塞合并的三个条件由format-spec-vote状态检查强制执行条件要求实现要点三个绑定 1 票3 位 PMC 成员批准 PR提案人除外只有最新 commit 上的批准有效——推送新 commit 会使旧批准失效tally_reviews中按commit_id head_sha判定无否决票无 PMC 成员持有未解决的 Request changes 评审请求变更即 −1 绑定票视为否决veto直到撤回前一直阻塞合并最短投票期距投票开启至少 72 小时周末不计入 72 小时投票期在 PR 同时具备format-change标签且退出 Draft 后开启取两者较晚者从源码可以看到更多细节每位评审者只统计其最近一次立场评审_STANCE_STATES仅包含 APPROVED / CHANGES_REQUESTED / DISMISSEDCOMMENTED 与 PENDING 被忽略PR 作者即使身为 PMC 也永远不计入周末边界固定在 UTCWEEKEND_TZ timezone.utc避免 DST 与时区争议而截止时间在注释中以 UTC 和太平洋时间双时区显示。PMC 名册从 docs/src/community/pmc.yaml 读取每 15 分钟重新评估一次因此统计注释与状态检查会比评审滞后几分钟。判定优先级decide_verdict依次为否决票 批准数不足 投票期未满 通过。对于不改变格式的琐碎编辑错别字、措辞、格式调整PMC 成员可打format-waived标签免除投票。投票期的纯函数逻辑投票开启时刻与截止时刻的计算被刻意实现为纯函数vote_opened_at、weekday_deadline并由 ci/test_format_vote_gate.py 以参数化测试全面覆盖运行方式为pytest ci/test_format_vote_gate.py。测试用例清晰地展示了周末排除规则的实际效果周一 09:00 开启截止为周四 09:00整 72 小时偏移周五 17:00 开启周六前累积 7 小时剩余 65 小时从下周一 00:00 继续最终落在周三 17:00——周五下午的提案仍能获得三个完整工作日周末期间开启时钟从周一才开始计跨多个周末的长投票期会跳过不止一个周末如 6 天时长实际截止在下一个周一。AI Tooling Integrations持续改进 AI 工具链Lance 社区鼓励贡献者持续改进与 AI 工具的集成具体包括三个方面增强编码 Agent 指南如根目录及各子项目下的AGENTS.md、CLAUDE.md本仓库可见 AGENTS.md、rust/AGENTS.md、python/AGENTS.md、java/AGENTS.md、protos/AGENTS.md、docs/src/format/AGENTS.md向 AI 代码评审者提供反馈帮助改进 AI 辅助评审的质量开发与改进 AI 驱动的 GitHub Actions如自动打标签、自动投票门等工作流。这些指南文件本身就是高度工程化的例如 AGENTS.md 详细规定了开发命令cargo check --workspace --tests --benches、cargo clippy --all --tests --benches -- -D warnings、cargo fmt --all、编码标准Rust/Python/Java 绑定保持薄封装、永不破坏公开 API 签名、用indices而非indexes、测试标准没有测试的代码不合并、向量索引测试必须断言 recall 指标不低于 0.5、跳过测试必须关联 GitHub issue以及 PR 提交前的 lint 检查要求。项目专属贡献指南CONTRIBUTING.md 与实战建议每个项目在各自的CONTRIBUTING.md中维护详细的贡献指南。以仓库根目录的 CONTRIBUTING.md 为例它为新贡献者提供了从零开始的完整路径环境准备安装 Rust、Python 3.10、protobuf3.20 及以上版本、pre-commit 并运行pre-commit install示例工作流Fork 仓库 → 选择 issue → 创建分支 → 修改 → 从 fork 发起 PR → 反馈迭代 → 合并评审标准Rust 公开 API 优先使用 builder 模式或 options struct 而非长参数列表输入优先使用IntoT/AsRefT提升灵活性所有新公开 API 必须有文档与示例所有 bugfix 与功能必须有对应测试运行基准测试Rust 基准测试每日多次运行向量索引基准针对 sift1m 数据集另有 tpch 基准均位于benchmarks/目录。结合 AGENTS.md 的补充建议提交 PR 前的自查清单可以归纳为运行全部受影响语言面的 lint 检查Rust 侧cargo fmt --all与cargo clippy --all --tests --benches -- -D warningsPython 侧从python/目录执行uv run make lintPR 标题遵循 Conventional Commits破坏性变更打breaking-change标签关键修复打critical-fix标签若触碰格式规范路径则等待format-spec-vote门禁通过。总结Lance 的贡献体系可以概括为一条主线与两条支线主线是所有代码贡献通过 PR 提交并接受维护者评审两条支线分别是面向重大功能设计的 Discussion Draft PR 迭代流程以及面向格式规范变更的PR 即提案、PMC 结构化投票机制。对于贡献者而言理解 Conventional Commits 是融入提交历史的基础理解投票门的三个条件三票、无否决、72 小时则是推动格式演进的关键。相关文档与实现均可在仓库中继续深入研读docs/src/community/contributing.md、docs/src/community/voting.md、ci/format_vote_gate.py、ci/test_format_vote_gate.py。【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考