|
1 | | -# 向 Certimate 贡献代码 |
| 1 | +# 贡献指南 |
2 | 2 |
|
3 | | -感谢你抽出时间来改进 Certimate！以下是向 Certimate 主仓库提交 PR（Pull Request）时的操作指南。 |
| 3 | +非常感谢你抽出时间来帮助改进 Certimate！以下是向 Certimate 提交 Pull Request 时的操作指南。 |
4 | 4 |
|
5 | | -- [向 Certimate 贡献代码](#向-certimate-贡献代码) |
6 | | - - [前提条件](#前提条件) |
7 | | - - [修改 Go 代码](#修改-go-代码) |
8 | | - - [修改管理页面 (Admin UI)](#修改管理页面-admin-ui) |
| 5 | +我们需要保持敏捷和快速迭代，同时也希望确保贡献者能获得尽可能流畅的参与体验。这份贡献指南旨在帮助你熟悉代码库和我们的工作方式，让你可以尽快进入有趣的开发环节。 |
9 | 6 |
|
10 | | -## 前提条件 |
| 7 | +索引： |
11 | 8 |
|
12 | | -- Go 1.24+ (用于修改 Go 代码) |
13 | | -- Node 20+ (用于修改 UI) |
| 9 | +- [开发](#开发) |
| 10 | + - [要求](#要求) |
| 11 | + - [后端代码](#后端代码) |
| 12 | + - [前端代码](#前端代码) |
| 13 | +- [提交 PR](#提交-pr) |
| 14 | + - [提交流程](#提交流程) |
| 15 | +- [获取帮助](#获取帮助) |
14 | 16 |
|
15 | | -如果还没有这样做，你可以 fork Certimate 的主仓库，并克隆到本地以便进行修改： |
| 17 | +--- |
16 | 18 |
|
17 | | -```bash |
18 | | -git clone https://github.com/your_username/certimate.git |
19 | | -``` |
| 19 | +## 开发 |
| 20 | + |
| 21 | +### 要求 |
20 | 22 |
|
21 | | -> **重要提示：** |
22 | | -> 建议为每个 Bug 修复或新功能创建一个从 `main` 分支派生的新分支。如果你计划提交多个 PR，请保持不同的改动在独立分支中，以便更容易进行代码审查并最终合并。 |
23 | | -> 保持一个 PR 只实现一个功能。 |
| 23 | +- Go 1.24+（用于修改后端代码） |
| 24 | +- Node.js 22.0+（用于修改前端代码） |
24 | 25 |
|
25 | | -## 修改 Go 代码 |
| 26 | +### 后端代码 |
26 | 27 |
|
27 | | -假设你已经对 Certimate 的 Go 代码做了一些修改，现在你想要运行它： |
| 28 | +Certimate 的后端代码是使用 Golang 开发的，是一个基于 [Pocketbase](https://github.com/pocketbase/pocketbase) 构建的单体应用。 |
28 | 29 |
|
29 | | -1. 进入根目录 |
30 | | -2. 运行以下命令启动服务： |
| 30 | +假设你已经对 Certimate 的后端代码做出了一些修改，现在你想要运行它，请遵循以下步骤： |
31 | 31 |
|
| 32 | +1. 进入根目录； |
| 33 | +2. 安装依赖： |
| 34 | + ```bash |
| 35 | + go mod vendor |
| 36 | + ``` |
| 37 | +3. 启动本地开发服务： |
32 | 38 | ```bash |
33 | 39 | go run main.go serve |
34 | 40 | ``` |
35 | 41 |
|
36 | | -这将启动一个 Web 服务器，默认运行在 `http://localhost:8090`，并使用来自 `ui/dist` 的预构建管理页面。 |
37 | | - |
38 | | -> 如果你遇到报错 `ui/embed.go:10:12: pattern all:dist: no matching files found` 请先参考 [构建 Admin UI](#修改管理页面-admin-ui) |
| 42 | +这将启动一个 Web 服务器，默认运行在 `http://localhost:8090`，并使用来自 `/ui/dist` 的预构建管理页面。 |
39 | 43 |
|
40 | | -**在向主仓库提交 PR 之前，建议你：** |
| 44 | +> 如果你遇到报错 `ui/embed.go: pattern all:dist: no matching files found`，请参考“[前端代码](#前端代码)”这一小节构建 WebUI。 |
41 | 45 |
|
42 | | -- 使用 [gofumpt](https://github.com/mvdan/gofumpt) 对你的代码进行格式化。 |
| 46 | +**在向主仓库提交 PR 之前，你应该：** |
43 | 47 |
|
44 | | -- 为你的改动添加单元测试或集成测试（Certimate 使用 Go 的标准 `testing` 包）。你可以通过以下命令运行测试（在项目根目录下）： |
| 48 | +- 使用 [gofumpt](https://github.com/mvdan/gofumpt) 格式化你的代码。推荐使用 VSCode，并安装 gofumpt 插件，以便在保存时自动格式化。 |
| 49 | +- 为你的改动添加单元测试或集成测试（使用 Go 标准库中的 `testing` 包）。 |
45 | 50 |
|
46 | | - ```bash |
47 | | - go test ./... |
48 | | - ``` |
| 51 | +### 前端代码 |
49 | 52 |
|
50 | | -## 修改管理页面 (Admin UI) |
| 53 | +Certimate 的前端代码是使用 TypeScript 开发的，是一个基于 [React](https://github.com/facebook/react) 和 [Vite](https://github.com/vitejs/vite) 构建的单页应用。 |
51 | 54 |
|
52 | | -Certimate 的管理页面是一个基于 React 和 Vite 构建的单页应用（SPA）。 |
53 | | - |
54 | | -要启动 Admin UI： |
55 | | - |
56 | | -1. 进入 `ui` 项目目录。 |
57 | | - |
58 | | -2. 运行 `npm install` 安装依赖。 |
| 55 | +假设你已经对 Certimate 的前端代码做出了一些修改，现在你想要运行它，请遵循以下步骤： |
59 | 56 |
|
| 57 | +1. 进入 `/ui` 目录； |
| 58 | +2. 安装依赖： |
| 59 | + ```bash |
| 60 | + npm install |
| 61 | + ``` |
60 | 62 | 3. 启动 Vite 开发服务器： |
61 | | - |
62 | 63 | ```bash |
63 | 64 | npm run dev |
64 | 65 | ``` |
65 | 66 |
|
66 | | -你可以通过浏览器访问 `http://localhost:5173` 来查看运行中的管理页面。 |
| 67 | +这将启动一个 Web 服务器，默认运行在 `http://localhost:5173`，你可以通过浏览器访问来查看运行中的 WebUI。 |
67 | 68 |
|
68 | | -由于 Admin UI 只是一个客户端应用，运行时需要 Certimate 的后端服务作为支撑。你可以手动运行 Certimate，或者使用预构建的可执行文件。 |
69 | | - |
70 | | -所有对 Admin UI 的修改将会自动反映在浏览器中，无需手动刷新页面。 |
71 | | - |
72 | | -完成修改后，运行以下命令来构建 Admin UI，以便它能被嵌入到 Go 包中： |
| 69 | +完成修改后，运行以下命令来构建 WebUI，以便它能被嵌入到 Go 包中： |
73 | 70 |
|
74 | 71 | ```bash |
75 | 72 | npm run build |
76 | 73 | ``` |
77 | 74 |
|
78 | | -完成所有步骤后，你可以将改动提交 PR 到 Certimate 主仓库。 |
| 75 | +**在向主仓库提交 PR 之前，你应该：** |
| 76 | + |
| 77 | +- 使用 [ESLint](https://github.com/eslint/eslint) 格式化你的代码。推荐使用 VSCode，并安装 ESLint+Prettier 插件，以便在保存时自动格式化。 |
| 78 | + |
| 79 | +## 提交 PR |
| 80 | + |
| 81 | +在提交 PR 之前，请先创建一个 Issue 来讨论你的修改方案，并等待来自项目维护者的反馈。这样做有助于： |
| 82 | + |
| 83 | +- 让我们充分理解你的修改内容； |
| 84 | +- 评估修改是否符合项目路线图； |
| 85 | +- 避免重复工作； |
| 86 | +- 防止你投入时间到可能无法被合并的修改中。 |
| 87 | + |
| 88 | +### 提交流程 |
| 89 | + |
| 90 | +1. Fork 本仓库； |
| 91 | +2. 在提交 PR 之前，请先发起 Issue 讨论你想要做的修改； |
| 92 | +3. 为你的修改创建一个新的分支； |
| 93 | +4. 请为你的修改添加相应的测试； |
| 94 | +5. 确保你的代码能通过现有的测试； |
| 95 | +6. 请在 PR 描述中关联相关 Issue； |
| 96 | +7. 等待合并！ |
| 97 | + |
| 98 | +> [!IMPORTANT] |
| 99 | +> |
| 100 | +> 建议为每个新功能或 Bug 修复创建一个从 `main` 分支派生的新分支。如果你计划提交多个 PR，请保持不同的改动在独立分支中，以便更容易进行代码审查并最终合并。 |
| 101 | +> |
| 102 | +> 保持一个 PR 只实现一个功能或修复。 |
| 103 | +
|
| 104 | +## 获取帮助 |
| 105 | + |
| 106 | +如果你在贡献过程中遇到困难或问题，可以通过 GitHub Issues 向我们提问。 |
0 commit comments