|
| 1 | +# 贡献指南 |
| 2 | + |
| 3 | +欢迎 issue 与 pull request。这个仓库的每一层都有硬约束,改动前请先读对应文档;本文只讲流程与规范。 |
| 4 | + |
| 5 | +## 1. 开始之前 |
| 6 | + |
| 7 | +| 想做什么 | 先读 | |
| 8 | +|---|---| |
| 9 | +| 改内核(C++) | [src/core/README.md](src/core/README.md) 的"硬约束" | |
| 10 | +| 改托管层(C#) | [src/csharp/managed/README.md](src/csharp/managed/README.md) | |
| 11 | +| 改启动器 / 宿主(Kotlin) | [架构](docs/architecture.md) 的分层与线程模型 | |
| 12 | +| 补文档 | 本文第 5 节 | |
| 13 | + |
| 14 | +本地环境准备与构建命令见 [构建](docs/build.md)。提交前至少跑通: |
| 15 | + |
| 16 | +```powershell |
| 17 | +pwsh -File src/csharp/tools/pylon.ps1 check |
| 18 | +pwsh -File src/csharp/tools/pylon.ps1 build |
| 19 | +``` |
| 20 | + |
| 21 | +真机相关的改动(内核、宿主、图形、导入流程)请在 PR 描述里附上 `pylon.ps1 run` 的日志片段。 |
| 22 | + |
| 23 | +## 2. 分支与提交 |
| 24 | + |
| 25 | +- 从 `main` 开分支:`feat/<范围>-<摘要>`、`fix/<范围>-<摘要>`、`docs/<摘要>`。 |
| 26 | +- 提交信息:`<范围>: <祈使句摘要>`,范围取 `app` / `game` / `core` / `managed` / `modloader` / `docs` / `tools`。 |
| 27 | +- 一个提交做一件事;格式化与逻辑改动分开,便于 review。 |
| 28 | +- 不要提交 `refs/`、`runtime/`、`interop/generated/`、`.work/`、构建产物或任何游戏文件。 |
| 29 | + |
| 30 | +## 3. 代码规范 |
| 31 | + |
| 32 | +通用: |
| 33 | + |
| 34 | +- 不写叙述性注释。注释只解释"为什么"(时序约束、平台坑、非直觉取舍),不解释"是什么"。 |
| 35 | +- 不留死代码与被注释掉的旧实现。 |
| 36 | +- 新增行为要有可观察的证据:日志阶段行、引用报告或真机验证结论。 |
| 37 | + |
| 38 | +### 内核(C++20) |
| 39 | + |
| 40 | +- 编译契约(flags、符号可见性、页对齐)在 [src/core/README.md](src/core/README.md),改动等于改动对外承诺。 |
| 41 | +- 不用异常与 RTTI;错误用 `Status` / `Outcome<T>` 表达。 |
| 42 | +- 不写死偏移与类名以外的假设;解析失败只降级,不带崩进程。 |
| 43 | +- 新增导出符号必须能在导出自检里看到。 |
| 44 | + |
| 45 | +### 托管层(C#) |
| 46 | + |
| 47 | +- `net10.0`,可空引用开启,`TreatWarningsAsErrors`,零警告基线。 |
| 48 | +- 一个文件一个公开类型;文件级命名空间;成员访问不写 `this.`。 |
| 49 | +- 已发布 API 不改成员形态(属性与字段互换会让老 Mod 抛 `MissingFieldException`)。 |
| 50 | +- 热路径不分配、不闭包、不拼字符串;分派前先判"有没有人覆写"。 |
| 51 | + |
| 52 | +### 启动器 / 宿主(Kotlin) |
| 53 | + |
| 54 | +- 状态以 `StateFlow` 暴露,UI 只读;不要在 Composable 里做 IO。 |
| 55 | +- 跨进程契约的常量放 `src/common`(如 `RuntimeLayout`),不要各写一份字符串。 |
| 56 | +- 日志统一走项目的 `Log` 封装,阶段行保持 `[stage] +Nms` 格式。 |
| 57 | + |
| 58 | +## 4. 测试 |
| 59 | + |
| 60 | +没有单元测试基线,验证以"可复现的真机回路"为准: |
| 61 | + |
| 62 | +| 改动 | 验证方式 | |
| 63 | +|---|---| |
| 64 | +| 托管层 / Mod 框架 | `pylon.ps1 managed` → 看 `[mod]` 与 `[hook]` 日志 | |
| 65 | +| 内核 | `pylon.ps1 build` → 看 `[boot]` 阶段与引用报告 | |
| 66 | +| 导入 / 版本门禁 | 用不同版本的已安装游戏走一遍导入,确认拒绝与放行的边界 | |
| 67 | +| 文档 | 命令复制到终端能跑;路径与链接指向真实文件 | |
| 68 | + |
| 69 | +PR 描述里写清:改了什么、为什么、怎么验证的、有什么已知副作用。 |
| 70 | + |
| 71 | +## 5. 文档规范 |
| 72 | + |
| 73 | +- 中文书写,GitHub 风格 Markdown;标题层级从 `#` 起,正文最多用到 `###`。 |
| 74 | +- 一份文档只回答一个问题;跨文档用相对链接互指,不复制整段内容。 |
| 75 | +- 命令一律用 `powershell` 代码块,路径用行内代码,术语保持统一:启动器 / 宿主 / 内核 / 托管层 / Mod / 导入。 |
| 76 | +- 面向读者的语气:陈述现状与约束,不写"我们尝试过…"的过程叙事;过程属于 issue 与 commit message。 |
| 77 | +- 新增能力时同步更新 [路线](docs/roadmap.md) 的"已完成 / 未实现"两张表。 |
| 78 | + |
| 79 | +## 6. 合规 |
| 80 | + |
| 81 | +- 不提交、不发布任何游戏文件或由游戏派生的代理程序集。 |
| 82 | +- 不实现、不合并绕过购买、许可或完整性校验的改动(含 PairIP)。 |
| 83 | +- 不复制 [Bunny Loader](https://github.com/JonataOliveiraa/Bunny-Loader) 等采用不兼容许可的上游代码;借鉴技术路线可以,代码请独立实现并在 PR 中说明来源。 |
| 84 | +- 新引入的第三方依赖必须与 [LICENSE](LICENSE) 兼容,并在 PR 中列出许可证。 |
0 commit comments