docs: add upage usage instructions document

2025-09-26 16:47:07 +08:00
parent 54d1d65642
commit 793782cd02
26 changed files with 10637 additions and 70 deletions
--- a/docs/content/contributing.md
+++ b/docs/content/contributing.md
@@ -0,0 +1,199 @@
+---
+id: contributing
+title: 贡献指南
+---
+
+# 贡献指南
+
+感谢您对 UPage 项目的关注！我们非常欢迎各种形式的贡献，无论是功能开发、bug 修复、文档改进还是使用反馈。本指南将帮助您了解如何参与 UPage 的开发和贡献。
+
+## 行为准则
+
+参与 UPage 项目的所有贡献者都应遵循以下行为准则：
+
+- 尊重所有参与者，无论其背景、经验或观点
+- 接受建设性的批评和反馈
+- 专注于对社区最有利的事情
+- 展现同理心和善意
+
+## 贡献方式
+
+您可以通过多种方式为 UPage 做出贡献：
+
+### 报告问题
+
+如果您发现了 bug 或有功能建议，请在 [GitHub Issues](https://github.com/halo-dev/upage/issues) 中提出。提交问题时，请尽可能提供以下信息：
+
+- 清晰的问题描述
+- 复现步骤
+- 预期行为与实际行为
+- 截图（如适用）
+- 环境信息（浏览器、操作系统、UPage 版本等）
+
+### 提交代码
+
+如果您想直接贡献代码，请遵循以下步骤：
+
+1. Fork 项目仓库
+2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 创建 Pull Request
+
+### 改进文档
+
+文档对于任何项目都至关重要。您可以通过以下方式改进 UPage 的文档：
+
+- 修复文档中的错误或不准确之处
+- 添加缺失的信息或示例
+- 改进文档的结构和可读性
+- 翻译文档到其他语言
+
+### 分享和推广
+
+您也可以通过以下方式支持 UPage：
+
+- 在社交媒体上分享项目
+- 撰写关于 UPage 的博客文章或教程
+- 在相关论坛和社区中推荐 UPage
+- 为项目加星标（Star）
+
+## 开发环境设置
+
+### 前置条件
+
+开始开发 UPage 前，请确保您的系统满足以下要求：
+
+- Node.js 18.18.0 或更高版本
+- pnpm 9.4.0 或更高版本
+- Git
+
+### 克隆仓库
+
+```bash
+git clone https://github.com/halo-dev/upage.git
+cd upage
+```
+
+### 安装依赖
+
+```bash
+pnpm install
+```
+
+### 启动开发服务器
+
+```bash
+pnpm dev
+```
+
+此命令会启动开发服务器，您可以通过 `http://localhost:3000` 访问。
+
+### 构建项目
+
+```bash
+pnpm build
+```
+
+### 运行测试
+
+```bash
+pnpm test
+```
+
+## 代码规范
+
+### JavaScript/TypeScript 规范
+
+UPage 使用 [Biome](https://biomejs.dev/) 进行代码格式化和 linting。在提交代码前，请确保您的代码符合项目的代码规范：
+
+```bash
+pnpm check
+```
+
+您也可以使用以下命令自动修复格式问题：
+
+```bash
+pnpm check --write
+```
+
+### Git 提交规范
+
+我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范来格式化 Git 提交信息。提交信息应遵循以下格式：
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+常用的 `type` 包括：
+
+- `feat`: 新功能
+- `fix`: 修复 bug
+- `docs`: 文档更新
+- `style`: 代码风格更改（不影响代码功能）
+- `refactor`: 代码重构
+- `perf`: 性能优化
+- `test`: 添加或修改测试
+- `chore`: 构建过程或辅助工具的变动
+
+例如：
+
+```
+feat(editor): 添加拖拽调整组件大小功能
+
+添加了一个新的拖拽句柄，允许用户直接调整组件的大小。
+同时优化了调整过程中的性能。
+
+Closes #123
+```
+
+## 分支策略
+
+- `main`: 主分支，包含稳定的代码
+- `develop`: 开发分支，包含最新的开发代码
+- `feature/*`: 功能分支，用于开发新功能
+- `fix/*`: 修复分支，用于修复 bug
+- `release/*`: 发布分支，用于准备新版本发布
+
+请基于 `develop` 分支创建您的功能或修复分支，并在完成后向 `develop` 分支提交 Pull Request。
+
+## Pull Request 流程
+
+1. 确保您的代码符合项目的代码规范
+2. 更新相关文档（如适用）
+3. 添加或更新测试（如适用）
+4. 确保所有测试通过
+5. 提交 Pull Request 到 `develop` 分支
+6. 在 PR 描述中详细说明您的更改
+
+## 版本发布流程
+
+UPage 遵循 [语义化版本控制](https://semver.org/) 规范。版本号格式为 `X.Y.Z`：
+
+- `X`: 主版本号，当进行不兼容的 API 更改时递增
+- `Y`: 次版本号，当添加向后兼容的功能时递增
+- `Z`: 修订号，当进行向后兼容的 bug 修复时递增
+
+## 文档贡献
+
+UPage 的文档使用 [Docusaurus](https://docusaurus.io/) 构建。如果您想贡献文档，请遵循以下步骤：
+
+1. 在 `docs` 目录中找到相关的 Markdown 文件
+2. 进行必要的更改
+3. 在本地预览更改：`pnpm docs:start`
+4. 提交 Pull Request
+
+## 社区
+
+加入 UPage 社区，与其他贡献者交流：
+
+- [GitHub Discussions](https://github.com/halo-dev/upage/discussions)
+- [GitHub Issues](https://github.com/halo-dev/upage/issues)
+
+## 许可证
+
+UPage 采用 [MIT 许可证](https://github.com/halo-dev/upage/blob/main/LICENSE)。通过贡献代码，您同意您的贡献将在相同的许可证下发布。