贡献指南
截至 2026 年 3 月。欢迎参与 Presto 生态的开发，无论你是修正一个错别字还是贡献一个新功能。
前置条件
开始贡献前，请确保你的开发环境已经搭建完成。参考 环境搭建指南 完成以下工具的安装：
- Git
- Node.js + npm
- Go（如果参与 Presto 主仓库开发）
- VSCode + Claude Code（推荐的 AI 辅助开发工具）
验证：运行 git --version && node --version && go version，确认所有工具可用。
分支策略
所有 Presto 仓库统一采用 main 单分支策略（GitHub Flow 简化模型）：
main是唯一的长期分支，始终保持可发布状态- 所有开发在从
main创建的短期特性分支上进行 - 没有 develop、release 等额外分支
特性分支命名规范：
| 前缀 | 用途 | 示例 |
|---|---|---|
feat/ | 新功能 | feat/dark-mode |
fix/ | 修复 Bug | fix/pdf-export-crash |
docs/ | 文档修改 | docs/update-glossary |
refactor/ | 代码重构 | refactor/template-engine |
开发流程
第 1 步：Fork 仓库
在 GitHub 上 Fork 目标仓库到你的账号下。
验证：浏览器中能看到 https://github.com/<你的用户名>/<仓库名>。
第 2 步：Clone 并配置上游
bash
git clone https://github.com/<你的用户名>/<仓库名>.git
cd <仓库名>
git remote add upstream https://github.com/Presto-io/<仓库名>.git验证：git remote -v 显示 origin（你的 Fork）和 upstream（Presto-io 原仓库）。
第 3 步：创建特性分支
bash
git checkout main
git pull upstream main
git checkout -b feat/你的功能名验证：git branch 显示当前在新分支上。
第 4 步：开发并提交
按照下方的 Commit 规范提交你的修改。建议小步提交，每个 commit 只做一件事。
第 5 步：推送并创建 PR
bash
git push origin feat/你的功能名然后在 GitHub 上创建 Pull Request，目标分支选择 upstream/main。
验证：GitHub 上能看到你的 PR，且 CI 检查开始运行。
Commit 规范
Commit 消息使用中文，格式为 <type>: <描述>。
| 类型 | 用途 | 示例 |
|---|---|---|
feat | 新功能 | feat: 添加暗色模式支持 |
fix | 修复 Bug | fix: 修复 PDF 导出时中文乱码 |
refactor | 重构（不改变行为） | refactor: 提取模板解析为独立模块 |
ui | 界面调整 | ui: 调整侧边栏宽度 |
sec | 安全相关 | sec: 修复路径遍历漏洞 |
docs | 文档修改 | docs: 更新术语表 |
chore | 构建/工具/依赖 | chore: 升级 Go 到 1.23 |
merge | 合并分支 | merge: 合并 feat/dark-mode |
PR 流程
项目目前没有 PR 模板，但建议你的 PR 描述包含以下内容：
- 做了什么：简要描述变更内容
- 为什么：说明变更的动机或关联的 issue（如有）
- 如何验证：描述如何测试你的修改
示例：
markdown
## 做了什么
添加了术语表中缺失的 3 个术语。
## 为什么
用户反馈在阅读模板开发指南时遇到不理解的术语。
## 如何验证
运行 `npm run check` 确认 lint 通过。提交 PR 后：
- 等待 CI 检查通过（如果有配置）
- 等待维护者 review
- 根据反馈修改后，push 到同一分支即可自动更新 PR
代码规范
各仓库有不同的技术栈和规范要求。完整的 AI 开发规范请参考 AI 开发指南。
Presto 主仓库（Go）
- 使用
gofmt格式化代码 - 错误处理：返回
error，不使用panic - 日志格式：
log.Printf("[module] ...") - 安全标注：使用
// SEC-XX:注释标记安全相关代码 - 不引入新的第三方 Go 依赖（除非事先讨论）
Presto 前端（Svelte 5 + TypeScript）
- 使用 Svelte 5 runes 语法（
$state、$derived、$effect） - TypeScript strict 模式
- 组件放在
frontend/src/lib/components/ - API 客户端放在
frontend/src/lib/api/ - 状态管理使用
.svelte.ts文件
Presto-doc（Markdown）
- 工具链：markdownlint-cli2 + prettier + autocorrect
- 行长限制 120 字符（表格除外）
- 提交前运行
npm run check确认零错误 - 仓库配置了 husky pre-commit hook，会自动检查暂存文件
首次贡献建议
不知道从哪里开始？以下是一些适合新手的贡献方向：
- 文档修正：修正错别字、过时链接、不准确的描述
- Dependabot PR Review：帮助 review 自动创建的依赖更新 PR，确认 CI 通过且无破坏性变更
- 用户体验改善：根据自己使用 Presto 的体验，提出改进建议或提交 issue
- 补充测试：为现有功能补充测试用例
每一个贡献都很有价值，期待你的参与。