Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
78 lines (58 loc) · 3.17 KB

CONTRIBUTING.md

File metadata and controls

78 lines (58 loc) · 3.17 KB
Raw

Contributing Guide

Thank you for your interest in contributing to the Official Document AI Assistant.

Development Setup

  1. Clone the repository
  2. Install Python 3.12+ and Node.js 20+
  3. Set up backend: cd backend && pip install -r requirements.txt
  4. Set up frontend: cd frontend && npm install

Code Style

  • Python: Follow PEP 8. Use type hints. Run ruff before committing.
  • TypeScript: Follow ESLint config. Use strict types.
  • Variables: English names. Comments in Chinese where necessary.

Commit Convention

  • feat: new feature
  • fix: bug fix
  • docs: documentation
  • refactor: code refactor
  • test: adding tests
  • chore: maintenance

⚠️ File & Commit Rules (MUST READ)

DO NOT Commit These Files

The following file types and paths must never be committed to the repository. They are excluded by .gitignore and checked by the pre-commit hook:

Category Examples Why
Office lock files ~$*.docx, ~$*.dotx Temporary files created by Office when a document is open
Old docs / reports docs/archive/, docs/reports/ Phase reports, one-time analysis docs (outdated)
Utility scripts frontend/build_electron.py, packaging/build_release.py, generate_icon.py, scripts/generate_missing_templates.py, tests/fixtures/create_test_doc.py One-time build helpers / template generators, run locally
Chinese-named files at root 启动应用.bat, 公文模板/ Cross-platform path encoding issues
Build outputs *.exe, *.msi, *.deb, *.AppImage, *.dmg Generated by CI, not tracked in source
Node/Python caches node_modules/, __pycache__/, .venv/ Dependency caches, platform-specific
Runtime data data/, output/, *.db, *.log User data, database, encryption keys
IDE files .vscode/, .idea/, *.swp, *.swo Editor-specific config
OS metadata .DS_Store, Thumbs.db OS-generated hidden files
Temp/backup files *.bak, *.tmp, *.pid Temporary artifacts

File Naming Rules

  1. All file/directory paths must use English characters (A-Z, a-z, 0-9, -, _, .).
    • ❌ 公文模板/, 启动应用.bat, API测试指南.md
    • ✅ dotx_templates/, startup.bat, api-test-guide.md
  2. Binary files (fonts, images, test fixtures) should be kept small and only committed if essential.
  3. Source code files must have correct extensions (.py, .ts, .tsx, .yaml, .json, etc.).

Install Pre-commit Hook

To prevent accidental commits of unwanted files, install the pre-commit hook:

# From project root, run:
git config core.hooksPath .githooks

After running this, Git will automatically check every commit for forbidden files.

Pull Request Process

  1. Create a feature branch from main
  2. Make your changes with tests
  3. Run all tests locally: pytest tests/
  4. Ensure no forbidden files are included (run git status to check)
  5. Submit a PR with a clear description