docs: edit CONTRIBUTING

This commit is contained in:
Fu Diwei 2025-06-17 20:22:53 +08:00
parent 9354c60380
commit 583d308459
4 changed files with 170 additions and 117 deletions

View File

@ -1,78 +1,106 @@
# 向 Certimate 贡献代码
# 贡献指南
感谢你抽出时间来改进 Certimate以下是向 Certimate 主仓库提交 PRPull Request时的操作指南。
非常感谢你抽出时间来帮助改进 Certimate以下是向 Certimate 提交 Pull Request 时的操作指南。
- [向 Certimate 贡献代码](#向-certimate-贡献代码)
- [前提条件](#前提条件)
- [修改 Go 代码](#修改-go-代码)
- [修改管理页面 (Admin UI)](#修改管理页面-admin-ui)
我们需要保持敏捷和快速迭代,同时也希望确保贡献者能获得尽可能流畅的参与体验。这份贡献指南旨在帮助你熟悉代码库和我们的工作方式,让你可以尽快进入有趣的开发环节。
## 前提条件
索引:
- Go 1.24+ (用于修改 Go 代码)
- Node 20+ (用于修改 UI)
- [开发](#开发)
- [要求](#要求)
- [后端代码](#后端代码)
- [前端代码](#前端代码)
- [提交 PR](#提交-pr)
- [提交流程](#提交流程)
- [获取帮助](#获取帮助)
如果还没有这样做,你可以 fork Certimate 的主仓库,并克隆到本地以便进行修改:
---
## 开发
### 要求
- Go 1.24+(用于修改后端代码)
- Node.js 22.0+(用于修改前端代码)
### 后端代码
Certimate 的后端代码是使用 Golang 开发的,是一个基于 [Pocketbase](https://github.com/pocketbase/pocketbase) 构建的单体应用。
假设你已经对 Certimate 的后端代码做出了一些修改,现在你想要运行它,请遵循以下步骤:
1. 进入根目录;
2. 安装依赖:
```bash
git clone https://github.com/your_username/certimate.git
go mod vendor
```
> **重要提示:**
> 建议为每个 Bug 修复或新功能创建一个从 `main` 分支派生的新分支。如果你计划提交多个 PR请保持不同的改动在独立分支中以便更容易进行代码审查并最终合并。
> 保持一个 PR 只实现一个功能。
## 修改 Go 代码
假设你已经对 Certimate 的 Go 代码做了一些修改,现在你想要运行它:
1. 进入根目录
2. 运行以下命令启动服务:
3. 启动本地开发服务:
```bash
go run main.go serve
```
这将启动一个 Web 服务器,默认运行在 `http://localhost:8090`,并使用来自 `ui/dist` 的预构建管理页面。
这将启动一个 Web 服务器,默认运行在 `http://localhost:8090`,并使用来自 `/ui/dist` 的预构建管理页面。
> 如果你遇到报错 `ui/embed.go:10:12: pattern all:dist: no matching files found` 请先参考 [构建 Admin UI](#修改管理页面-admin-ui)
> 如果你遇到报错 `ui/embed.go: pattern all:dist: no matching files found`,请参考“[前端代码](#前端代码)”这一小节构建 WebUI。
**在向主仓库提交 PR 之前,建议你:**
**在向主仓库提交 PR 之前,你应该:**
- 使用 [gofumpt](https://github.com/mvdan/gofumpt) 对你的代码进行格式化。
- 使用 [gofumpt](https://github.com/mvdan/gofumpt) 格式化你的代码。推荐使用 VSCode并安装 gofumpt 插件,以便在保存时自动格式化。
- 为你的改动添加单元测试或集成测试(使用 Go 标准库中的 `testing` 包)。
- 为你的改动添加单元测试或集成测试Certimate 使用 Go 的标准 `testing` 包)。你可以通过以下命令运行测试(在项目根目录下):
### 前端代码
Certimate 的前端代码是使用 TypeScript 开发的,是一个基于 [React](https://github.com/facebook/react) 和 [Vite](https://github.com/vitejs/vite) 构建的单页应用。
假设你已经对 Certimate 的前端代码做出了一些修改,现在你想要运行它,请遵循以下步骤:
1. 进入 `/ui` 目录;
2. 安装依赖:
```bash
go test ./...
npm install
```
## 修改管理页面 (Admin UI)
Certimate 的管理页面是一个基于 React 和 Vite 构建的单页应用SPA
要启动 Admin UI
1. 进入 `ui` 项目目录。
2. 运行 `npm install` 安装依赖。
3. 启动 Vite 开发服务器:
```bash
npm run dev
```
你可以通过浏览器访问 `http://localhost:5173` 来查看运行中的管理页面
这将启动一个 Web 服务器,默认运行在 `http://localhost:5173`,你可以通过浏览器访问来查看运行中的 WebUI。
由于 Admin UI 只是一个客户端应用,运行时需要 Certimate 的后端服务作为支撑。你可以手动运行 Certimate或者使用预构建的可执行文件。
所有对 Admin UI 的修改将会自动反映在浏览器中,无需手动刷新页面。
完成修改后,运行以下命令来构建 Admin UI以便它能被嵌入到 Go 包中:
完成修改后,运行以下命令来构建 WebUI以便它能被嵌入到 Go 包中:
```bash
npm run build
```
完成所有步骤后,你可以将改动提交 PR 到 Certimate 主仓库。
**在向主仓库提交 PR 之前,你应该:**
- 使用 [ESLint](https://github.com/eslint/eslint) 格式化你的代码。推荐使用 VSCode并安装 ESLint+Prettier 插件,以便在保存时自动格式化。
## 提交 PR
在提交 PR 之前,请先创建一个 Issue 来讨论你的修改方案,并等待来自项目维护者的反馈。这样做有助于:
- 让我们充分理解你的修改内容;
- 评估修改是否符合项目路线图;
- 避免重复工作;
- 防止你投入时间到可能无法被合并的修改中。
### 提交流程
1. Fork 本仓库;
2. 在提交 PR 之前,请先发起 Issue 讨论你想要做的修改;
3. 为你的修改创建一个新的分支;
4. 请为你的修改添加相应的测试;
5. 确保你的代码能通过现有的测试;
6. 请在 PR 描述中关联相关 Issue
7. 等待合并!
> [!IMPORTANT]
>
> 建议为每个新功能或 Bug 修复创建一个从 `main` 分支派生的新分支。如果你计划提交多个 PR请保持不同的改动在独立分支中以便更容易进行代码审查并最终合并。
>
> 保持一个 PR 只实现一个功能或修复。
## 获取帮助
如果你在贡献过程中遇到困难或问题,可以通过 GitHub Issues 向我们提问。

View File

@ -1,83 +1,106 @@
# Contributing to Certimate
# Contribution Guide
Thank you for taking the time to improve Certimate! Below is a guide for submitting a PR (Pull Request) to the main Certimate repository.
Thank you for taking the time to improve Certimate! Below is a guide for submitting a PR (Pull Request) to the Certimate repository.
- [Contributing to Certimate](#contributing-to-certimate)
We need to be nimble and ship fast given where we are, but we also want to make sure that contributors like you get as smooth an experience at contributing as possible. We've assembled this contribution guide for that purpose, aiming at getting you familiarized with the codebase & how we work with contributors, so you could quickly jump to the fun part.
Index:
- [Development](#development)
- [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)
- [Backend Code](#backend-code)
- [Frontend Code](#frontend-code)
- [Submitting PR](#submitting-pr)
- [Pull Request Process](#pull-request-process)
- [Getting Help](#getting-help)
## Prerequisites
---
- Go 1.24+ (for Go code changes)
- Node 20+ (for Admin UI changes)
## Development
If you haven't done so already, you can fork the Certimate repository and clone your fork to work locally:
### Prerequisites
```bash
git clone https://github.com/your_username/certimate.git
```
- Go 1.24+ (for backend code changes)
- Node.js 22.0+ (for frontend code changes)
> **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.
### Backend Code
## Making Changes in the Go Code
The backend code of Certimate is developed using Golang. It is a monolithic application based on [Pocketbase](https://github.com/pocketbase/pocketbase).
Once you have made changes to the Go code in Certimate, follow these steps to run the project:
Once you have made changes to the backend code in Certimate, follow these steps to run the project:
1. Navigate to the root directory.
2. Start the service by running:
2. Install dependencies:
```bash
go mod vendor
```
3. Start the local development server:
```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`.
This will start a web server at `http://localhost:8090` using the prebuilt WebUI located in `/ui/dist`.
> if you encounter an error `ui/embed.go:10:12: pattern all:dist: no matching files found`, please refer to [build Admin UI](#making-changes-in-the-admin-ui)
> If you encounter an error `ui/embed.go: pattern all:dist: no matching files found`, please refer to _[Frontend Code](#frontend-code)_ and build WebUI first.
**Before submitting a PR to the main repository, consider:**
**Before submitting a PR to the main repository, you should:**
- Format your source code by using [gofumpt](https://github.com/mvdan/gofumpt).
- Format your source code by using [gofumpt](https://github.com/mvdan/gofumpt). Recommended using VSCode and installing the gofumpt plugin to automatically format when saving.
- Adding unit or integration tests for your changes (with go standard library `testing` package).
- 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):
### Frontend Code
```bash
go test ./...
```
The frontend code of Certimate is developed using TypeScript. It is a SPA based on [React](https://github.com/facebook/react) and [Vite](https://github.com/vitejs/vite).
## 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:
Once you have made changes to the backend code in Certimate, follow these steps to run the project:
1. Navigate to the `/ui` directory.
2. Install dependencies:
```bash
npm install
```
3. Start the Vite development server:
3. Start the local development server:
```bash
npm run dev
```
You can now access the running Admin UI at `http://localhost:5173` in your browser.
This will start a web server at `http://localhost:5173`. You can now access the WebUI 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:
After completing your changes, build the WebUI 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.
**Before submitting a PR to the main repository, you should:**
- Format your source code by using [ESLint](https://github.com/eslint/eslint). Recommended using VSCode and installing the ESLint plugin to automatically format when saving.
## Submitting PR
Before opening a Pull Request, please open an issue to discuss the change and get feedback from the maintainers. This will helps us:
- To understand the context of the change.
- To ensure it fits into Certimate's roadmap.
- To prevent us from duplicating work.
- To prevent you from spending time on a change that we may not be able to accept.
### Pull Request Process
1. Fork the repository.
2. Before you draft a PR, please open an issue to discuss the changes you want to make.
3. Create a new branch for your changes.
4. Please add tests for your changes accordingly.
5. Ensure your code passes the existing tests.
6. Please link the issue in the PR description.
7. Get merged!
> [!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.
## Getting Help
If you ever get stuck or get a burning question while contributing, simply shoot your queries our way via the GitHub issues.

View File

@ -5,8 +5,8 @@
[![Stars](https://img.shields.io/github/stars/certimate-go/certimate?style=flat)](https://github.com/certimate-go/certimate)
[![Forks](https://img.shields.io/github/forks/certimate-go/certimate?style=flat)](https://github.com/certimate-go/certimate)
[![Docker Pulls](https://img.shields.io/docker/pulls/certimate/certimate?style=flat)](https://hub.docker.com/r/certimate/certimate)
[![Release](https://img.shields.io/github/v/release/certimate-go/certimate?sort=semver)](https://github.com/certimate-go/certimate/releases)
[![License](https://img.shields.io/github/license/certimate-go/certimate)](https://mit-license.org/)
[![Release](https://img.shields.io/github/v/release/certimate-go/certimate?style=flat&sort=semver)](https://github.com/certimate-go/certimate/releases)
[![License](https://img.shields.io/github/license/certimate-go/certimate?style=flat)](https://mit-license.org/)
</div>
@ -71,10 +71,10 @@ Certimate 旨在为用户提供一个安全、简便的 SSL 证书管理解决
相关文章:
- [使用 CNAME 完成 ACME DNS-01 质询](https://docs.certimate.me/blog/cname)
- [v0.3.0:第二个不向后兼容的大版本](https://docs.certimate.me/blog/v0.3.0)
- [v0.2.0:第一个不向后兼容的大版本](https://docs.certimate.me/blog/v0.2.0)
- [Why Certimate?](https://docs.certimate.me/blog/why-certimate)
- [使用 CNAME 完成 ACME DNS-01 质询](https://docs.certimate.me/blog/cname)
- [v0.3.0:第二个不向后兼容的大版本](https://docs.certimate.me/blog/v0.3.0)
- [v0.2.0:第一个不向后兼容的大版本](https://docs.certimate.me/blog/v0.2.0)
- [Why Certimate?](https://docs.certimate.me/blog/why-certimate)
## ⭐ 运行界面
@ -82,18 +82,19 @@ Certimate 旨在为用户提供一个安全、简便的 SSL 证书管理解决
## 🤝 参与贡献
Certimate 是一个免费且开源的项目,采用 [MIT License](./LICENSE)。你可以使用它做任何你想做的事,甚至把它当作一个付费服务提供给用户
Certimate 是一个免费且开源的项目。我们欢迎任何人为 Certimate 做出贡献,以帮助改善 Certimate。包括但不限于提交代码、反馈缺陷、交流想法或分享你基于 Certimate 的使用案例。同时,我们也欢迎用户在个人博客或社交媒体上分享 Certimate
你可以通过以下方式来支持 Certimate 的开发:
如果你想要贡献代码,请先阅读我们的[贡献指南](./CONTRIBUTING.md)。
- 提交代码:如果你发现了 Bug 或有新的功能需求,而你又有相关经验,可以[提交代码](CONTRIBUTING.md)给我们。
- 提交 Issue功能建议或者 Bug 可以[提交 Issue](https://github.com/certimate-go/certimate/te/issues) 给我们。
请在 https://github.com/certimate-go/certimate 提交 [Issues](https://github.com/certimate-go/certimate/issues) 和 [Pull Requests](https://github.com/certimate-go/certimate/pulls)。
支持更多提供商、UI 的优化改进、Bug 修复、文档完善等,欢迎大家参与贡献。
#### 感谢以下贡献者对 Certimate 做出的贡献:
[![Contributors](https://contrib.rocks/image?repo=certimate-go/certimate)](https://github.com/certimate-go/certimate/graphs/contributors)
## ⛔ 免责声明
Certimate 基于 [MIT License](https://opensource.org/licenses/MIT) 发布,完全免费提供,旨在“按现状”供用户使用。作者及贡献者不对使用本软件所产生的任何直接或间接后果承担责任,包括但不限于性能下降、数据丢失、服务中断、或任何其他类型的损害。
Certimate 遵循 [MIT License](https://opensource.org/licenses/MIT) 开源协议,完全免费提供,旨在“按现状”供用户使用。作者及贡献者不对使用本软件所产生的任何直接或间接后果承担责任,包括但不限于性能下降、数据丢失、服务中断、或任何其他类型的损害。
**无任何保证**:本软件不提供任何明示或暗示的保证,包括但不限于对特定用途的适用性、无侵权性、商用性及可靠性的保证。
@ -104,7 +105,7 @@ Certimate 基于 [MIT License](https://opensource.org/licenses/MIT) 发布,完
- [Telegram](https://t.me/+ZXphsppxUg41YmVl)
- 微信群聊(超 200 人需邀请入群,可先加作者好友)
<img src="https://i.imgur.com/8xwsLTA.png" width="240"/>
<img src="https://i.imgur.com/8xwsLTA.png" width="200"/>
## 🚀 Star 趋势图

View File

@ -65,14 +65,14 @@ Work with Certimate right now. Or read other content in the documentation to lea
## 📄 Documentation
Please visit the documentation site [docs.certimate.me](https://docs.certimate.me/en/).
For full documentation, please visit [docs.certimate.me](https://docs.certimate.me/en/).
Related articles:
- [使用 CNAME 完成 ACME DNS-01 质询](https://docs.certimate.me/blog/cname)
- [v0.3.0:第二个不向后兼容的大版本](https://docs.certimate.me/blog/v0.3.0)
- [v0.2.0:第一个不向后兼容的大版本](https://docs.certimate.me/blog/v0.2.0)
- [Why Certimate?](https://docs.certimate.me/blog/why-certimate)
- [_使用 CNAME 完成 ACME DNS-01 质询_](https://docs.certimate.me/blog/cname)
- [_v0.3.0:第二个不向后兼容的大版本_](https://docs.certimate.me/blog/v0.3.0)
- [_v0.2.0:第一个不向后兼容的大版本_](https://docs.certimate.me/blog/v0.2.0)
- [_Why Certimate?_](https://docs.certimate.me/blog/why-certimate)
## ⭐ Screenshot
@ -80,18 +80,19 @@ Related articles:
## 🤝 Contributing
Certimate is a free and open-source project, licensed under the [MIT License](./LICENSE). You can use it for anything you want, even offering it as a paid service to users.
Certimate is a free and open-source project, and your feedback and contributions are needed and always welcome. Contributions include but are not limited to: submitting code, reporting bugs, sharing ideas, or showcasing your use cases based on Certimate. We also encourage users to share Certimate on personal blogs or social media.
You can support the development of Certimate in the following ways:
For those who'd like to contribute code, see our [Contribution Guide](./CONTRIBUTING_EN.md).
- **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/certimate-go/certimate/te/issues) to us.
[Issues](https://github.com/certimate-go/certimate/issues) and [Pull Requests](https://github.com/certimate-go/certimate/pulls) are opened at https://github.com/certimate-go/certimate.
Support for more service providers, UI enhancements, bug fixes, and documentation improvements are all welcome. We encourage everyone to contribute.
#### Contributors
[![Contributors](https://contrib.rocks/image?repo=certimate-go/certimate)](https://github.com/certimate-go/certimate/graphs/contributors)
## ⛔ Disclaimer
This software is provided under the [MIT License](https://opensource.org/licenses/MIT) and distributed “as-is” without any warranty of any kind. The authors and contributors are not responsible for any damages or losses resulting from the use or inability to use this software, including but not limited to data loss, business interruption, or any other potential harm.
This repository is available under the [MIT License](https://opensource.org/licenses/MIT), and distributed “as-is” without any warranty of any kind. The authors and contributors are not responsible for any damages or losses resulting from the use or inability to use this software, including but not limited to data loss, business interruption, or any other potential harm.
**No Warranties**: This software comes without any express or implied warranties, including but not limited to implied warranties of merchantability, fitness for a particular purpose, and non-infringement.
@ -102,7 +103,7 @@ This software is provided under the [MIT License](https://opensource.org/license
- [Telegram](https://t.me/+ZXphsppxUg41YmVl)
- Wechat Group
<img src="https://i.imgur.com/zSHEoIm.png" width="240"/>
<img src="https://i.imgur.com/zSHEoIm.png" width="200"/>
## 🚀 Star History