198 lines
4.4 KiB
Markdown
198 lines
4.4 KiB
Markdown
# 贡献指南
|
||
|
||
感谢您考虑为 Sharp-Basic Framework 做出贡献！
|
||
|
||
## 📜 行为准则
|
||
|
||
请遵守以下基本原则：
|
||
- 尊重所有贡献者
|
||
- 保持友好和包容的态度
|
||
- 接受建设性的批评
|
||
- 专注于对社区最有利的事情
|
||
|
||
## 🚀 如何贡献
|
||
|
||
### 报告 Bug
|
||
|
||
如果您发现了 bug，请创建一个 Issue 并包含以下信息：
|
||
1. **标题**: 简洁描述问题
|
||
2. **环境**: 操作系统、.NET 版本、项目版本
|
||
3. **复现步骤**: 详细的步骤
|
||
4. **预期行为**: 应该发生什么
|
||
5. **实际行为**: 实际发生了什么
|
||
6. **日志/截图**: 如果有的话
|
||
|
||
### 提出新功能
|
||
|
||
在开始编码之前：
|
||
1. 先创建一个 Issue 讨论您的想法
|
||
2. 等待维护者的反馈
|
||
3. 确保功能符合项目的整体方向
|
||
|
||
### 提交代码
|
||
|
||
#### 准备工作
|
||
```bash
|
||
# Fork 项目到您的账号
|
||
# Clone 到本地
|
||
git clone https://gitea.duyl328.org/您的用户名/sharp-basic.git
|
||
cd sharp-basic
|
||
|
||
# 添加上游仓库
|
||
git remote add upstream https://gitea.duyl328.org/jimmy/sharp-basic.git
|
||
|
||
# 创建功能分支
|
||
git checkout -b feature/您的功能名称
|
||
```
|
||
|
||
#### 代码规范
|
||
|
||
1. **命名约定**
|
||
- 类名：PascalCase（如 `ConfigManager`）
|
||
- 方法名：PascalCase（如 `BuildConfiguration`）
|
||
- 私有字段：_camelCase（如 `_logger`）
|
||
- 参数/局部变量：camelCase（如 `userName`）
|
||
|
||
2. **注释规范**
|
||
- 所有公共 API 必须有 XML 文档注释
|
||
- 使用中文编写注释和文档
|
||
- 复杂逻辑需要添加行内注释
|
||
|
||
3. **代码风格**
|
||
- 启用 nullable 引用类型
|
||
- 使用 `var` 当类型明显时
|
||
- 一行不超过 120 字符
|
||
- 使用 4 个空格缩进（不使用 Tab）
|
||
|
||
4. **测试要求**
|
||
- 新功能必须包含单元测试
|
||
- 测试覆盖率应 >= 80%
|
||
- 使用 MSTest 框架
|
||
- 测试方法命名: `方法名_场景_预期结果`
|
||
|
||
#### 提交信息规范
|
||
|
||
使用以下格式：
|
||
```
|
||
<类型>(<模块>): <简短描述>
|
||
|
||
<详细描述（可选）>
|
||
|
||
<关联 Issue（如果有）>
|
||
```
|
||
|
||
**类型**：
|
||
- `feat`: 新功能
|
||
- `fix`: Bug 修复
|
||
- `docs`: 文档更新
|
||
- `style`: 代码格式调整（不影响功能）
|
||
- `refactor`: 重构
|
||
- `test`: 测试相关
|
||
- `chore`: 构建/工具相关
|
||
|
||
**示例**：
|
||
```
|
||
feat(Config): 添加 TOML 格式支持
|
||
|
||
实现了基于 Tomlyn 的 TOML 配置文件解析功能
|
||
支持热重载和强类型绑定
|
||
|
||
Closes #123
|
||
```
|
||
|
||
#### Pull Request 流程
|
||
|
||
1. **确保代码质量**
|
||
```bash
|
||
# 运行所有测试
|
||
dotnet test
|
||
|
||
# 构建项目
|
||
dotnet build -c Release
|
||
```
|
||
|
||
2. **同步上游更改**
|
||
```bash
|
||
git fetch upstream
|
||
git rebase upstream/main
|
||
```
|
||
|
||
3. **提交 PR**
|
||
- 填写清晰的 PR 标题和描述
|
||
- 关联相关的 Issue
|
||
- 确保 CI 通过（如果有）
|
||
- 等待代码审查
|
||
|
||
4. **代码审查**
|
||
- 维护者会审查您的代码
|
||
- 根据反馈进行修改
|
||
- 保持耐心和礼貌
|
||
|
||
## 📂 项目结构
|
||
|
||
```
|
||
src/Sharp/ # 所有源代码项目
|
||
├── Common/ # 核心工具库
|
||
├── Config/ # 配置管理
|
||
├── Data/ # 数据访问层
|
||
├── Log/ # 日志模块
|
||
├── Wpf/ # WPF 基础库
|
||
└── ...
|
||
|
||
test/ # 测试项目
|
||
├── Common.Test/
|
||
├── Config.Test/
|
||
└── ...
|
||
```
|
||
|
||
## 🔧 开发环境设置
|
||
|
||
### 必需工具
|
||
- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
|
||
- [Git](https://git-scm.com/)
|
||
- 推荐 IDE：
|
||
- [Visual Studio 2022](https://visualstudio.microsoft.com/) (Windows)
|
||
- [Rider](https://www.jetbrains.com/rider/) (跨平台)
|
||
- [VS Code](https://code.visualstudio.com/) + C# 扩展
|
||
|
||
### 首次构建
|
||
```bash
|
||
# 还原依赖
|
||
dotnet restore
|
||
|
||
# 构建解决方案
|
||
dotnet build Sharp.sln
|
||
|
||
# 运行测试
|
||
dotnet test
|
||
```
|
||
|
||
## 📋 待办事项
|
||
|
||
查看 [Issues](https://gitea.duyl328.org/jimmy/sharp-basic/issues) 页面了解：
|
||
- 标记为 `good first issue` 的任务适合新贡献者
|
||
- 标记为 `help wanted` 的任务需要帮助
|
||
|
||
## 📝 文档贡献
|
||
|
||
文档同样重要！您可以：
|
||
- 改进现有文档的清晰度
|
||
- 添加示例代码
|
||
- 修正错别字
|
||
- 翻译文档（如果需要）
|
||
|
||
## ⚖️ 许可证
|
||
|
||
提交代码即表示您同意将您的贡献以 [AGPL-3.0-or-later](LICENSE) 许可证发布。
|
||
|
||
## 💬 联系方式
|
||
|
||
如有任何问题：
|
||
- 创建 [Issue](https://gitea.duyl328.org/jimmy/sharp-basic/issues)
|
||
- 查看 [README](README.md) 获取更多信息
|
||
- 访问作者网站: [https://seyl.me/](https://seyl.me/)
|
||
|
||
---
|
||
|
||
再次感谢您的贡献！🎉
|