Add contributing guide

This commit is contained in:
yoan 2024-09-27 07:26:11 +08:00
parent 46080b311a
commit 993ef7bf57
4 changed files with 148 additions and 3 deletions

72
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,72 @@
# 向 Certimate 贡献代码
感谢你抽出时间来改进 Certimate以下是向 Certimate 主仓库提交 PRPull Request时的操作指南。
- [向 Certimate 贡献代码](#向-certimate-贡献代码)
- [前提条件](#前提条件)
- [修改 Go 代码](#修改-go-代码)
- [修改管理页面 (Admin UI)](#修改管理页面-admin-ui)
## 前提条件
- Go 1.22+ (用于修改 Go 代码)
- Node 20+ (用于修改 UI)
如果还没有这样做,你可以 fork Certimate 的主仓库,并克隆到本地以便进行修改:
```bash
git clone https://github.com/your_username/certimate.git
```
> **重要提示:**
> 建议为每个 bug 修复或新功能创建一个从 `main` 分支派生的新分支。如果你计划提交多个 PR请保持不同的改动在独立分支中以便更容易进行代码审查并最终合并。
> 保持一个 pr 只实现一个功能。
## 修改 Go 代码
假设你已经对 Certimate 的 Go 代码做了一些修改,现在你想要运行它:
1. 进入根目录
2. 运行以下命令启动服务:
```bash
go run main.go serve
```
这将启动一个 Web 服务器,默认运行在 `http://localhost:8090`,并使用来自 `ui/dist` 的预构建管理页面。
**在向主仓库提交 PR 之前,建议你:**
- 为你的改动添加单元测试或集成测试Certimate 使用 Go 的标准 `testing` 包)。你可以通过以下命令运行测试(在项目根目录下):
```bash
go test ./...
```
## 修改管理页面 (Admin UI)
Certimate 的管理页面是一个基于 React 和 Vite 构建的单页应用SPA
要启动 Admin UI
1. 进入 `ui` 项目目录
2. 运行 `npm install` 安装依赖
3. 启动 Vite 开发服务器:
```bash
npm run dev
```
你可以通过浏览器访问 `http://localhost:5173` 来查看运行中的管理页面。
由于 Admin UI 只是一个客户端应用,运行时需要 Certimate 的后端服务作为支撑。你可以手动运行Certimate或者使用预构建的可执行文件。
所有对 Admin UI 的修改将会自动反映在浏览器中,无需手动刷新页面。
完成修改后,运行以下命令来构建 Admin UI以便它能被嵌入到 Go 包中:
```bash
npm run build
```
完成所有步骤后,你可以将改动提交 PR 到 Certimate 主仓库。

73
CONTRIBUTING_EN.md Normal file
View File

@ -0,0 +1,73 @@
# Contributing to Certimate
Thank you for taking the time to improve Certimate! Below is a guide for submitting a PR (Pull Request) to the main Certimate repository.
- [Contributing to Certimate](#contributing-to-certimate)
- [Prerequisites](#prerequisites)
- [Making Changes in the Go Code](#making-changes-in-the-go-code)
- [Making Changes in the Admin UI](#making-changes-in-the-admin-ui)
## Prerequisites
- Go 1.22+ (for Go code changes)
- Node 20+ (for Admin UI changes)
If you haven't done so already, you can fork the Certimate repository and clone your fork to work locally:
```bash
git clone https://github.com/your_username/certimate.git
```
> **Important:**
> It is recommended to create a new branch from `main` for each bug fix or feature. If you plan to submit multiple PRs, ensure the changes are in separate branches for easier review and eventual merge.
> Keep each PR focused on a single feature or fix.
## Making Changes in the Go Code
Once you have made changes to the Go code in Certimate, follow these steps to run the project:
1. Navigate to the root directory.
2. Start the service by running:
```bash
go run main.go serve
```
This will start a web server at `http://localhost:8090` using the prebuilt Admin UI located in `ui/dist`.
**Before submitting a PR to the main repository, consider:**
- Adding unit or integration tests for your changes. Certimate uses Gos standard `testing` package. You can run tests using the following command (while in the root project directory):
```bash
go test ./...
```
## Making Changes in the Admin UI
Certimates Admin UI is a single-page application (SPA) built using React and Vite.
To start the Admin UI:
1. Navigate to the `ui` project directory.
2. Install the necessary dependencies by running:
```bash
npm install
```
3. Start the Vite development server:
```bash
npm run dev
```
You can now access the running Admin UI at `http://localhost:5173` in your browser.
Since the Admin UI is a client-side application, you will also need to have the Certimate backend running. You can either manually run Certimate or use a prebuilt executable.
Any changes you make in the Admin UI will be automatically reflected in the browser without requiring a page reload.
After completing your changes, build the Admin UI so it can be embedded into the Go package:
```bash
npm run build
```
Once all steps are completed, you are ready to submit a PR to the main Certimate repository.

View File

@ -161,7 +161,7 @@ Certimate 是一个免费且开源的项目,采用 [MIT 开源协议](LICENSE.
你可以通过以下方式来支持 Certimate 的开发: 你可以通过以下方式来支持 Certimate 的开发:
* 提交代码:如果你发现了 bug 或有新的功能需求,而你又有相关经验,可以提交代码给我们。 * [提交代码:如果你发现了 bug 或有新的功能需求,而你又有相关经验,可以提交代码给我们](CONTRIBUTING.md)
* 提交 issue功能建议或者 bug 可以[提交 issue](https://github.com/usual2970/certimate/issues) 给我们。 * 提交 issue功能建议或者 bug 可以[提交 issue](https://github.com/usual2970/certimate/issues) 给我们。
支持更多服务商、UI 的优化改进、BUG 修复、文档完善等,欢迎大家提交 PR。 支持更多服务商、UI 的优化改进、BUG 修复、文档完善等,欢迎大家提交 PR。

View File

@ -163,7 +163,7 @@ Certimate is a free and open-source project, licensed under the [MIT License](LI
You can support the development of Certimate in the following ways: You can support the development of Certimate in the following ways:
* **Submit Code**: If you find a bug or have new feature requests, and you have relevant experience, you can submit code to us. * **Submit Code**: If you find a bug or have new feature requests, and you have relevant experience, [you can submit code to us](CONTRIBUTING_EN.md).
* **Submit an Issue**: For feature suggestions or bugs, you can [submit an issue](https://github.com/usual2970/certimate/issues) to us. * **Submit an Issue**: For feature suggestions or bugs, you can [submit an issue](https://github.com/usual2970/certimate/issues) to us.
Support for more service providers, UI enhancements, bug fixes, and documentation improvements are all welcome. We encourage everyone to submit pull requests (PRs). Support for more service providers, UI enhancements, bug fixes, and documentation improvements are all welcome. We encourage everyone to submit pull requests (PRs).
@ -174,4 +174,4 @@ Support for more service providers, UI enhancements, bug fixes, and documentatio
* Wechat Group * Wechat Group
<img src="https://i.imgur.com/lJUfTeD.png" width="400"/> <img src="https://i.imgur.com/zSHEoIm.png" width="400"/>