e3d6b60825
Phase 1 (Infrastructure): - Docs: README.md, AGENTS.md, CHANGELOG.md - Tests: 26 tests (modes_test, filetree_api_test) - Examples: examples/sample.md, sample.json - CI/CD: .gitea/workflows/test.yml, release.yml - Runner: configuration scripts and guides Phase 2 (Quality): - Code quality: rustfmt/clippy config - Security: environment variables - Test coverage: 62 tests (+36) - Documentation: CONTRIBUTING.md, docs/api.yaml - Showcase: demo_features.md, developer_quickstart.md Test coverage: 75% Test pass rate: 100%
223 lines
3.3 KiB
Markdown
223 lines
3.3 KiB
Markdown
# 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授權。貢獻的代碼將以相同授權發布。
|
||
|
||
---
|
||
|
||
**感謝您的貢獻！** |