尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

Apache Maka 贡献指南:从 Issue 认领、本地构建到 PR 审查的完整工作流

Apache Maka 贡献指南:从 Issue 认领、本地构建到 PR 审查的完整工作流 Apache Maka 贡献指南从 Issue 认领、本地构建到 PR 审查的完整工作流【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/makaApache MakaIncubating是一个基于事件溯源event sourcing的 Agent 工作区代码组织为 npm workspaces 多包仓库。本文基于官方贡献文档 CONTRIBUTING.zh-CN.md 整理完整覆盖“找活干 → 环境搭建 → 本地构建与测试 → 推送前对齐 CI → 提 PR”的全链路并结合.asf.yaml、pre-commit 钩子与 CI 工作流等仓库内实现细节解释每条规则背后的机制帮助你在提交第一个补丁前先理解这个仓库的质量门禁。从哪里开始任务来源与认领约定贡献文档明确列出了最容易被合并的贡献类型缺陷修复、模型供应商支持、测试、性能优化和文档。官方建议从 issue 的help wanted、good first issue、bug、enhancement标签中挑选任务并留言认领。提 issue 使用Bug report或Feature request模板仓库内对应 bug_report.yml 和 feature_request.yml安全问题必须走 SECURITY.md 的私密流程不要开公开 issue提问、想法和不成熟的提案则发到 Discussions——它会自动同步到邮件列表比 issue 更容易被看到。两个容易踩坑的细节认领协议只认两个单词若要自助认领一个尚未分配的 issue评论正文必须只能是take这一个单词评论untake解除自己的认领。其他任何认领文字都不会触发该工作流。仓库中对应的自动化实现是 take.yml。决策分层项目方向、治理和重大产品决策在实施前于开发邮件列表devmaka.apache.org上公开讨论实现层面的技术决策可以直接在 PR 中讨论。人类责任与 AI 归因这份贡献文档有一个显著特点它显式定义了 Agent 参与贡献时的责任边界这在 Apache 孵化项目中比较少见。每项贡献都有一名 human contributor of record由人负责审阅、决定提交并对准确性、来源和许可负责。Agent 可以自由 commit 和 push但最终的审查与合并决定始终由人做出。每个 PR 必须声明生成式工具是否有实质贡献有则注明工具名称。翻译、措辞整理、自动补全和拼写修正不算实质贡献。自动发送的消息必须表明身份。Generated-bytrailerAI 创作了贡献中的实质部分时需要在每个受影响的 commit 上加Generated-by: tooltrailer并确保它在 squash 或 amend 后保留于最终 commit。AI 生成的实质内容遵循 ASF 生成式工具指南。这一约定在 pull_request_template.md 中有落地模板的 “## AI use” 小节要求二选一勾选“No generative tool made a substantive contribution” 或 “Generative tooling made a substantive contribution”并在选中后者时要求列出工具名称和作用范围附注“给受影响的 commit 加 Generated-by trailer并保证最终 squash commit 保留该 trailer”。审查机制一位独立 committer 必过的 test 检查向main提的每个 PR 需要满足两个条件才能合并一位作者之外的 committer 给出 approval且必需的test检查通过。这套机制由 .asf.yaml 的protected_branches声明式强制执行protected_branches: main: required_pull_request_reviews: dismiss_stale_reviews: false required_approving_review_count: 1 required_status_checks: strict: false contexts: - test这里的配置有几个值得注意的设计文件中的注释解释得很清楚dismiss_stale_reviews: falseGitHub 在收到新 commit 时会丢弃旧 approval但不会丢弃“请求修改”。如果开启 stale 丢弃rebase 一次就要重新走一整轮 approval而未解决的反对意见却原样存活——两半审查以不同速率衰减代价不对称。test是 CI 中唯一的无条件 jobci.yml 把计划planning和验证放在同一个 job 里文档类改动只付一次 runner 配额。注释特别警告改名为其他名字、给 ci.yml 加 paths filter、或把工作拆回多个 job 让必需检查来自可被跳过的聚合器都会让必需上下文在部分 PR 上永远不报告从而冻结所有合并。分支按钮只留 squashenabled_merge_buttons中仅squash: true且del_branch_on_merge: true。这也解释了为什么 PR 标题会成为落到main上的提交信息见后文。审查必须出自独立的人工判断贡献文档明确写了“AI review 不算”。一个改动是否重大、获得的审查是否足够由维护者认定。另外.asf.yaml还通过 rulesets 禁止删除或 force pushv*发布标签并声明了release、npm-publication、nightly、product-release等受保护环境作为签名密钥与 npm OIDC 的部署边界——这些不是贡献者日常接触的部分但解释了发布流程为什么需要环境级人工复核。环境要求快速开始一节给出的硬性版本约束与根 package.json 中的声明一致Node22.19.0对应engines.nodenpm11.19.0对应packageManager: npm11.19.0若要开发Desktop Direct Peer或Peer Mesh功能还需要 Rust stable1.98或更高版本以及 macOS 的 Xcode Command Line Tools 或 Windows 的 MSVC Build Tools。仓库内 gitoxide-helper 的 rust-toolchain.toml 固定channel 1.98.0而 runtime-host-peer 的 rust-toolchain.toml 使用stable与文档描述吻合。仓库共声明了 11 个 workspacemaka/core、maka/storage、maka/mcp、maka/runtime、maka/runtime-host、maka/eval、maka/computer-use、maka-agentCLI 包、maka/ui、maka/desktop、maka/website架构总览见 ARCHITECTURE.zh-CN.mdEval 的命令与 contract 见 packages/eval 目录下的文档。构建与测试为什么测试跑的是 dist初始化与构建命令注意注释npm install 只在根目录跑不要在某个 workspace 里跑git clone https://github.com/apache/maka.git cd maka npm install # 只在根目录装 —— 不要在某个 workspace 里跑 npm run build # 按依赖顺序构建全部 workspace npm --workspace maka/core run test:dist这里有两个机制值得展开1.npm run build是按依赖顺序串起来的。根package.json中build脚本的真实内容是一整条链core → storage → mcp → runtime → runtime-host → computer-use → eval → maka-agent → ui → desktop因此“只有依赖都已构建好时单独构建某个 workspace 才会成功——拿不准就从根目录构建”。链上任何一个 workspace 缺dist/下游的 TypeScript 编译就会失败。2. 测试跑的是编译产物不是源码。每个 workspace 的test:dist脚本执行的是node --test作用于dist/**/*.test.js例如 packages/cli/package.json 中test:dist: node --test \dist/**/*.test.js\apps/desktop/package.json 中则针对dist/main/**/*.test.js加上若干脚本级测试。也就是说test:dist覆盖的是最近一次构建的结果——如果你改了源码没重新构建跑测试得到的结论是过期的。根目录的npm test会把两步都做掉# package.json 中 test: npm run build:test node scripts/run-workspace-tests-parallel.mjs --concurrency3, build:test: npm run clean ... 各 workspace 依序 build ...build:test会先执行clean——由 clean-build.mjs 移除所有 workspace 的dist/和增量 tsbuildinfo。脚本头部的注释直言这是为了解决反复出现的 “tests pass on stale dist”测试跑在陈旧的 dist 上陷阱“每次移除/重命名一个 export旧 dist 都会存活测试就会说谎。”多 workspace 的并行调度由 run-workspace-tests-parallel.mjs 负责其行为来自脚本 JSDoc 与常量定义包括--concurrency N限制并发避免压垮小型 runner--workspaces a,b只跑选定的 workspace以每个 workspace 测试源码的字节数作为权重最重的套件优先入队防止短队列先抽干并发槽位每个 workspace 默认15 分钟超时DEFAULT_WORKSPACE_TIMEOUT_MS 15 * 60_000workspace 自己通过package.json的test:dist决定如何跑测试脚本只负责调度、进程驻留上限、失败报告和临时目录命名空间。日常开发命令npm run dev # 带 HMR 的桌面应用 npm run cli:dev # TUInpm run cli:dev -- run … 非交互地跑一个 Turn npm test # 全部 workspace或npm --workspace maka/core run test:dist从根package.json看dev实际执行maka/desktop的dev:hmr即node scripts/dev.mjscli:dev执行node packages/cli/dist/dev-cli.js涉及 Peer 的变体是npm run dev:peer会先触发prepare:runtime-host-peer构建 Rust 原生模块。推送前本地对齐 CI贡献文档给出的推送前检查清单逐条对应仓库里的真实实现npm run lint # biome lint . npm run format:check # biome format . npm run build # 全部 workspace 依序构建 npm run typecheck # npm run typecheck --workspaces --if-present npx knip --workspace apps/desktop # 未使用依赖/导出检查 npx knip --workspace packages/ui其中lint、format:check、typecheck都是根package.json的脚本分别对应biome lint .、biome format .和跨 workspace 的tsc检查knip 的两个 workspace 参数与 knip.json 中声明的apps/desktop、packages/ui两份 entry/project 配置一一对应——knip 只在这两个 workspace 做了完整入口声明所以 CI 也只检查这两个。除了手动跑这些检查还有提交时的自动化版本根package.json的prepare脚本会执行 install-husky.mjs 安装 Git 钩子而 .husky/pre-commit 钩子在每次 commit 时运行四项检查node scripts/biome-staged-check.mjs # 仅对 staged 文件跑 biome node scripts/asf-license-headers.mjs check-staged # 检查 Apache 许可头 node scripts/protocol-epoch-check.mjs --staged # Runtime Host 兼容 epoch 守卫 git diff --cached --check # 空白错误等其中 protocol-epoch-check.mjs 的头部注释解释了它防的是一个真实 bug 类别两个分支各自升级 Runtime Host 兼容 epoch 时写的是同一行同一段文本git 三方合并不会报冲突结果就是两个不兼容的协议宣称同一个 epoch。该检查在 PR 合并结果上与第一个父提交base 分支对比不兼容的变更必须移动 epochpre-commit 的--staged模式只能对 HEAD 判断最终裁决权在合并结果上。提出 Pull Request模板必须在此基础上填写不要整段替换。开 PR 时 GitHub 会自动填充 pull_request_template.md包含Summary含Fixes #N/Refs #N指引、Verification实际运行过的检查及其结果未运行的相关检查要点名用户可见的改动要附最轻量的证据截图、录屏或命令输出、AI use二选一并注明工具与作用范围和Checklist测试覆盖该变更且无它时会失败lint/format/typecheck/受影响套件本地通过是否改变行为。模板还提示只有当 PR 改变审查、发布或运维方式时才加额外小节并按真实风险命名如 Breaking change、Rollout、Root cause。命名遵循 Conventional Commits分支名type/描述PR 标题type(scope): summary。由于本仓库只允许 squash 合并.asf.yaml中 merge/rebase 按钮均为 falsePR 标题就是落到main上的提交信息仓库的git log里可以看到实际在用的 type 和 scope 集合。界面改动附截图或录屏改前改后都要有。描述写短用你自己的话——文档的原话是如果需要很多段落多半是这个 PR 太大了。来源与许可的底线贡献文档最后一条原则只提交你有权贡献的内容记录第三方来源、许可和必要署名贡献以 Apache License 2.0 授权。仓库把这条原则也做成了可执行检查根package.json提供check:asf-headers由 asf-license-headers.mjs 实现同时被 pre-commit 钩子以check-staged模式调用、generate:third-party-notices/check:third-party-notices、check:release等脚本分别覆盖许可头、第三方声明和发布产物审计。如果你要引入新的第三方依赖这些check:*脚本就是判断改动是否“完整”的现成标准。小结环节关键规则仓库内依据找活干认领评论只能是take/untaketake.ymlAI 归因声明工具 Generated-bytrailer 保留到最终 commitpull_request_template.md合并门禁1 个外部 approval test检查squash-only.asf.yaml、ci.yml环境Node ≥22.19.0npm 11.19.0Peer 需 Rust ≥1.98package.json测试跑dist/产物npm test clean build 并行 test:distrun-workspace-tests-parallel.mjs提交时biome staged、ASF 许可头、epoch 守卫、diff --check.husky/pre-commit推送前lint / format:check / build / typecheck / knipdesktop、ui根 package.json、knip.json按这份流程走完一遍你就具备了在这个仓库上提第一个可合并 PR 的全部知识任务从带标签的 issue 来环境在根目录一次性装好构建与测试永远从dist/出发推送前用四条命令加两次 knip 对齐 CIPR 标题即最终提交信息。【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表