# Contributing to MarkBase

感謝您考慮為 MarkBase做出貢獻！本文件提供開發流程與貢獻指南。

---

##開發環境設定

###必要條件

- Rust 1.92+ 
- macOS（音訊功能需要）
- SwitchAudioSource（音訊裝置切換）

###設定步驟

1. **克隆倉庫**
   ```bash
   git clone https://gitea.momentry.ddns.net/your-username/markbase.git
   cd markbase
   ```

2. **安裝 Rust**
   ```bash
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   ```

3. **安裝 macOS工具**
   ```bash
   brew install switchaudio-source
   ```

4. **建構專案**
   ```bash
   cargo build
   ```

---

##開發流程

###分支策略

- `main` -主分支（穩定版本）
- `develop` -開發分支（最新變更）
- `feature/*` -功能分支
- `fix/*` -修復分支

###提交訊息格式

使用以下格式：

```
<type>: <subject>

<body>

<footer>
```

**類型（type）：**
- `feat` -新功能
- `fix` -修復錯誤
- `docs` -文檔變更
- `style` -代碼格式
- `refactor` -重構
- `test` -測試相關
- `chore` -構建/工具變更

**範例：**
```
feat: add file upload API endpoint

Add POST /api/v2/upload/:user_id endpoint for file upload with SHA256 hashing.

Closes #123
```

---

##代碼標準

###格式化

執行代碼格式化：

```bash
cargo fmt
```

### Lint檢查

執行 clippy檢查：

```bash
cargo clippy --all-targets --all-features -- -D warnings
```

**重要：** 所有 clippy警告必須在提交前修復。

###測試

執行所有測試：

```bash
cargo test --all
```

**測試覆蓋率要求：**
- 新功能必須包含測試
-測試覆蓋率需達 60%以上

---

##提交前檢查清單

提交前請確認：

- [ ]代碼已格式化（`cargo fmt`）
- [ ] clippy檢查無警告
- [ ]所有測試通過（`cargo test --all`）
- [ ]文檔已更新（若需要）
- [ ] CHANGELOG已更新（若需要）

---

## Pull Request流程

###建立 PR

1.建立功能分支
   ```bash
   git checkout -b feature/your-feature
   ```

2.進行變更並提交
   ```bash
   git add .
   git commit -m "feat: your feature description"
   ```

3.推送到遠端
   ```bash
   git push origin feature/your-feature
   ```

4.在 Gitea建立 Pull Request
   - URL: https://gitea.momentry.ddns.net
   -選擇目標分支（`develop`或 `main`）
   -填寫 PR標題與描述

### PR審核

-至少需要 1個審核者同意
- CI測試必須通過
-解決所有審核意見

---

##文檔貢獻

###文檔位置

- README.md -專案說明
- AGENTS.md -開發指南
- CHANGELOG.md -版本記錄
- docs/filetree.md -File Tree架構
- docs/gitea_runner_setup.md - Runner配置

###文檔標準

-使用中英文對照
-保持簡潔清晰
-包含範例代碼

---

##問題回報

###回報步驟

1.檢查是否已有相同問題
2.建立新 Issue
3.提供詳細資訊：
   -問題描述
   -重現步驟
   -環境資訊
   -預期結果與實際結果

---

##代碼審核標準

###審核重點

-代碼可讀性
-測試覆蓋率
-效能影響
-安全性
-文檔完整性

###審核時間

-通常在 2-3個工作天內完成

---

##社群規範

-尊重所有貢獻者
-保持友善與專業
-接受不同意見
-專注於改進專案

---

##授權

本專案使用 MIT授權。貢獻的代碼將以相同授權發布。

---

**感謝您的貢獻！**