feat: MarkBase initial version

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%
2026-05-16 15:37:37 +08:00
commit e3d6b60825
50 changed files with 7758 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,223 @@
+# 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授權。貢獻的代碼將以相同授權發布。
+
+---
+
+**感謝您的貢獻！**