如何快速上手Astrid开发面向新手的Polyrepo Git工作流完整指南【免费下载链接】handbookContributor handbook for Astrid: the polyrepo, public contracts, contribution process, and release workflow.项目地址: https://gitcode.com/gh_mirrors/handbook76/handbookAstrid贡献者手册handbook是面向新手开发者的一份 Polyrepo Git 工作流完整指南。它详细解答了三个核心问题Astrid 的各个仓库如何组织polyrepo 布局、哪些改动必须先写 RFC、以及你的第一个 Pull Request 如何通过 CI 检查。读完本文你就能按项目标准完成一次合规的提交。先搞懂Astrid 的 Polyrepo 是什么结构Astrid不是monorepo。内核、SDK、RFC 和每一个胶囊capsule各自是独立的 git 仓库。你本地的工作目录只是把所有仓库按固定路径叠在一起本地路径职责core/内核、守护进程、CLI全部astrid-*核心 cratessdk-rust/astrid-sdk、astrid-sdk-macros、astrid-sysastrid-rfcs/内核-用户空间契约的设计提案RFCcapsules/astrid-capsule-name/各类胶囊如capsule-cli、capsule-http等 20 个最容易踩的坑git命令只作用于包含你当前目录的那个仓库。在 polyrepo 根目录执行git status看到的是父目录视图而不是内核的。动手前永远先cd进目标组件目录。命名规律很好记胶囊目录叫astrid-capsule-name远端仓库名去掉前缀只留capsule-name。快速开始克隆仓库与环境准备git clone https://gitcode.com/gh_mirrors/handbook76/handbook本地阅读这份手册只需 mdBookmdbook serve --open手册目录结构一览都在src/下入门src/introduction.mdPolyrepo 与 Git 工作流src/handbook/polyrepo-and-workflow.md内核无脑定律src/handbook/the-kernel-is-dumb-law.mdRFC 触发条件src/handbook/rfc-trigger.md贡献者等级src/handbook/contribution-tiers.md发布流程与编码标准src/handbook/release-and-standards.md分支管理永远从 origin/main 切出本地main经常是过期的。标准动作是先 fetch、再从远端切分支cd core # 或 sdk-rust、astrid-rfcs、capsules/astrid-capsule-name git fetch origin git checkout -b feat/your-feature origin/main三条硬性约定绝不直接提交到main任何改动无论多小都走分支分支名采用 Conventional Commits 风格feat/add-auth、fix/timeout-bug、refactor/config-loader提交信息格式为type(scope): description常见 type 有feat、fix、docs、test、ci等破坏性变更追加!并附BREAKING CHANGE:尾注。提交签名所有 commit 必须 GPG 签名推送前验证签名状态git log --format%H %G? -5G?字段应为G有效签名。显示N无签名的提交在正式分支上不允许推送。若环境沙箱拦截 GPG 导致gpg failed to sign the data按手册指引使用dangerouslyDisableSandbox: true重试即可。第一个 PR 怎么过 CIIssue-First 规则这是新手最容易被卡住的环节。Astrid 的 CI 有 5 道 PR 检查定义在core/.github/workflows/pr-checks.ymlCI 任务卡什么linked-issuePR 正文必须含Closes #N没有 issue 就先建一个template四个模板章节Linked Issue / Summary / Changes / Test Plan必须填实contributor-gate按贡献者等级限制可改动的 cratefile-size源文件不得超过 1000 行changelog动了.rs或Cargo.toml必须在CHANGELOG.md的[Unreleased]下加条目无 issue 的惊喜 PR会被直接关闭请一定先开 issue 再写代码。⚠️什么时候需要写 RFC七问自查清单改动是否触及内核与用户空间之间的契约面决定你需不需要 RFC。开 PR 前自问这 7 个问题出自src/handbook/rfc-trigger.md增删改了wit/host/下的函数→ 需要 RFC增删改了wit/interfaces/下的类型→ 需要 RFC改了内核据此做路由/门禁决策的CapsuleManifest字段→ 需要 RFC改了跨胶囊 IPC 的主题命名或负载结构→ 需要 RFC改了胶囊可见的能力capability匹配/校验规则→ 需要 RFC增删 VFS 方案或改了路径解析语义→ 需要 RFC从astrid-sdk删除了公开符号或改了函数签名→ 需要 RFC七个都是否就是内核内部改动直接写代码即可。典型无需 RFC 的场景修 bug、保持外部契约的重构、文档改进、新增实现现有接口的胶囊。记住架构铁律内核是笨的内核只做三件事路由事件、执行能力门禁、管理 WASM 沙箱。它不含任何业务逻辑。一句话判据如果内核不路由、不门禁、不校验它那它就属于胶囊空间的 IPC不该进内核。新手常见误区想给内核加首选模型会话上下文这类字段——错。模型选择、提示词组装、工具分发全部是胶囊的职责capsule-session、capsule-prompt-builder、capsule-react。贡献者等级你能改哪些代码CI 会读core/.github/contributors.yml判定你的等级New默认先开 issue等维护者打newcomer-approved标签后 CI 才放行Astrinaut可认领 issue改 CLI、SDK、胶囊、文档、测试不能碰安全关键与核心 cratesCore可改核心 crates碰安全关键路径需维护者共同评审Maintainer全量权限其中astrid-crypto、astrid-capabilities、astrid-audit等 8 个安全关键 crate 构成安全边界等级不够的 PR 会被 CI 硬性拦截。推送前 10 项检查清单1. cd 进了正确的仓库 2. 分支从 origin/main 切出 3. 分支名符合 feat/ fix/ refactor/ docs/ 约定 4. commit 已 GPG 签名 5. cargo test --workspace 通过胶囊则 cargo build 6. 无新增 Clippy 警告 7. CHANGELOG.md 已更新 [Unreleased] 8. 核心 PR 已关联 issue 并写 Closes #N 9. 版本号升级单独走一个 PR 10. 通过 HTTPS 推送到正确的远端仓库版本升级永远单独成 PR绝不混进功能或修复提交。延伸阅读完整工作流细节src/handbook/polyrepo-and-workflow.md内核边界与真实正反例src/handbook/the-kernel-is-dumb-law.md发布流程、CI 矩阵与 lint 标准src/handbook/release-and-standards.md掌握这套 Polyrepo Git 工作流你的每个提交都会又快又稳地通过 Astrid 的 CI。动手写第一个 issue 吧【免费下载链接】handbookContributor handbook for Astrid: the polyrepo, public contracts, contribution process, and release workflow.项目地址: https://gitcode.com/gh_mirrors/handbook76/handbook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何快速上手Astrid开发：面向新手的Polyrepo Git工作流完整指南
如何快速上手Astrid开发面向新手的Polyrepo Git工作流完整指南【免费下载链接】handbookContributor handbook for Astrid: the polyrepo, public contracts, contribution process, and release workflow.项目地址: https://gitcode.com/gh_mirrors/handbook76/handbookAstrid贡献者手册handbook是面向新手开发者的一份 Polyrepo Git 工作流完整指南。它详细解答了三个核心问题Astrid 的各个仓库如何组织polyrepo 布局、哪些改动必须先写 RFC、以及你的第一个 Pull Request 如何通过 CI 检查。读完本文你就能按项目标准完成一次合规的提交。先搞懂Astrid 的 Polyrepo 是什么结构Astrid不是monorepo。内核、SDK、RFC 和每一个胶囊capsule各自是独立的 git 仓库。你本地的工作目录只是把所有仓库按固定路径叠在一起本地路径职责core/内核、守护进程、CLI全部astrid-*核心 cratessdk-rust/astrid-sdk、astrid-sdk-macros、astrid-sysastrid-rfcs/内核-用户空间契约的设计提案RFCcapsules/astrid-capsule-name/各类胶囊如capsule-cli、capsule-http等 20 个最容易踩的坑git命令只作用于包含你当前目录的那个仓库。在 polyrepo 根目录执行git status看到的是父目录视图而不是内核的。动手前永远先cd进目标组件目录。命名规律很好记胶囊目录叫astrid-capsule-name远端仓库名去掉前缀只留capsule-name。快速开始克隆仓库与环境准备git clone https://gitcode.com/gh_mirrors/handbook76/handbook本地阅读这份手册只需 mdBookmdbook serve --open手册目录结构一览都在src/下入门src/introduction.mdPolyrepo 与 Git 工作流src/handbook/polyrepo-and-workflow.md内核无脑定律src/handbook/the-kernel-is-dumb-law.mdRFC 触发条件src/handbook/rfc-trigger.md贡献者等级src/handbook/contribution-tiers.md发布流程与编码标准src/handbook/release-and-standards.md分支管理永远从 origin/main 切出本地main经常是过期的。标准动作是先 fetch、再从远端切分支cd core # 或 sdk-rust、astrid-rfcs、capsules/astrid-capsule-name git fetch origin git checkout -b feat/your-feature origin/main三条硬性约定绝不直接提交到main任何改动无论多小都走分支分支名采用 Conventional Commits 风格feat/add-auth、fix/timeout-bug、refactor/config-loader提交信息格式为type(scope): description常见 type 有feat、fix、docs、test、ci等破坏性变更追加!并附BREAKING CHANGE:尾注。提交签名所有 commit 必须 GPG 签名推送前验证签名状态git log --format%H %G? -5G?字段应为G有效签名。显示N无签名的提交在正式分支上不允许推送。若环境沙箱拦截 GPG 导致gpg failed to sign the data按手册指引使用dangerouslyDisableSandbox: true重试即可。第一个 PR 怎么过 CIIssue-First 规则这是新手最容易被卡住的环节。Astrid 的 CI 有 5 道 PR 检查定义在core/.github/workflows/pr-checks.ymlCI 任务卡什么linked-issuePR 正文必须含Closes #N没有 issue 就先建一个template四个模板章节Linked Issue / Summary / Changes / Test Plan必须填实contributor-gate按贡献者等级限制可改动的 cratefile-size源文件不得超过 1000 行changelog动了.rs或Cargo.toml必须在CHANGELOG.md的[Unreleased]下加条目无 issue 的惊喜 PR会被直接关闭请一定先开 issue 再写代码。⚠️什么时候需要写 RFC七问自查清单改动是否触及内核与用户空间之间的契约面决定你需不需要 RFC。开 PR 前自问这 7 个问题出自src/handbook/rfc-trigger.md增删改了wit/host/下的函数→ 需要 RFC增删改了wit/interfaces/下的类型→ 需要 RFC改了内核据此做路由/门禁决策的CapsuleManifest字段→ 需要 RFC改了跨胶囊 IPC 的主题命名或负载结构→ 需要 RFC改了胶囊可见的能力capability匹配/校验规则→ 需要 RFC增删 VFS 方案或改了路径解析语义→ 需要 RFC从astrid-sdk删除了公开符号或改了函数签名→ 需要 RFC七个都是否就是内核内部改动直接写代码即可。典型无需 RFC 的场景修 bug、保持外部契约的重构、文档改进、新增实现现有接口的胶囊。记住架构铁律内核是笨的内核只做三件事路由事件、执行能力门禁、管理 WASM 沙箱。它不含任何业务逻辑。一句话判据如果内核不路由、不门禁、不校验它那它就属于胶囊空间的 IPC不该进内核。新手常见误区想给内核加首选模型会话上下文这类字段——错。模型选择、提示词组装、工具分发全部是胶囊的职责capsule-session、capsule-prompt-builder、capsule-react。贡献者等级你能改哪些代码CI 会读core/.github/contributors.yml判定你的等级New默认先开 issue等维护者打newcomer-approved标签后 CI 才放行Astrinaut可认领 issue改 CLI、SDK、胶囊、文档、测试不能碰安全关键与核心 cratesCore可改核心 crates碰安全关键路径需维护者共同评审Maintainer全量权限其中astrid-crypto、astrid-capabilities、astrid-audit等 8 个安全关键 crate 构成安全边界等级不够的 PR 会被 CI 硬性拦截。推送前 10 项检查清单1. cd 进了正确的仓库 2. 分支从 origin/main 切出 3. 分支名符合 feat/ fix/ refactor/ docs/ 约定 4. commit 已 GPG 签名 5. cargo test --workspace 通过胶囊则 cargo build 6. 无新增 Clippy 警告 7. CHANGELOG.md 已更新 [Unreleased] 8. 核心 PR 已关联 issue 并写 Closes #N 9. 版本号升级单独走一个 PR 10. 通过 HTTPS 推送到正确的远端仓库版本升级永远单独成 PR绝不混进功能或修复提交。延伸阅读完整工作流细节src/handbook/polyrepo-and-workflow.md内核边界与真实正反例src/handbook/the-kernel-is-dumb-law.md发布流程、CI 矩阵与 lint 标准src/handbook/release-and-standards.md掌握这套 Polyrepo Git 工作流你的每个提交都会又快又稳地通过 Astrid 的 CI。动手写第一个 issue 吧【免费下载链接】handbookContributor handbook for Astrid: the polyrepo, public contracts, contribution process, and release workflow.项目地址: https://gitcode.com/gh_mirrors/handbook76/handbook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考