# 贡献指南

感谢您考虑为 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/)

---

再次感谢您的贡献！🎉