From 6afe1fd244fcff0cfb77120b2c357525d6ad3eaf Mon Sep 17 00:00:00 2001 From: whuwkl Date: Sat, 2 Aug 2025 23:35:09 +0800 Subject: [PATCH] chore(docs): formal dev related docs --- .github/ISSUE_TEMPLATE/bug_report.md | 62 +++++++ .github/ISSUE_TEMPLATE/feature_request.md | 79 +++++++++ .github/PULL_REQUEST_TEMPLATE.md | 2 +- CONTRIBUTING.md | 199 +++++++++------------- README.md | 27 ++- 5 files changed, 242 insertions(+), 127 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..f98d202 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,62 @@ +--- +name: 🐛 Bug Report +about: Report a bug to help us improve QuantMind +title: 'bug: [brief description of the bug]' +labels: ['bug', 'needs-triage'] +assignees: '' +--- + +## 🐛 Bug Description + + + +## 🔄 Steps to Reproduce + +1. +2. +3. + +## ✅ Expected Behavior + + + +## ❌ Actual Behavior + + + +## 📋 Environment + +- **QuantMind Version**: +- **Python Version**: +- **Operating System**: +- **Installation Method**: + +## 📝 Additional Context + + + +### Error Logs + +``` + +``` + +### Configuration + +```yaml +# If relevant, paste your QuantMind configuration here +``` + +## 🛠️ Possible Solution + + + +--- + +**Checklist** + +- [ ] I have searched existing issues to avoid duplicates +- [ ] I have provided a clear and concise description +- [ ] I have included steps to reproduce the issue +- [ ] I have included my environment information +- [ ] I have included relevant error logs or screenshots diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..bd93879 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,79 @@ +--- +name: ✨ Feature Request +about: Suggest a new feature or enhancement for QuantMind +title: 'feat: [brief description of the feature]' +labels: ['enhancement', 'needs-triage'] +assignees: '' +--- + +## ✨ Feature Summary + + + +## 🎯 Motivation + + + +## 📋 Detailed Description + + + +## 🔧 Proposed Implementation + + + +### API Design + +```python +# If applicable, show how you envision the API would look +``` + +### Configuration + +```yaml +# If applicable, show any new configuration options +``` + +## 🎨 User Experience + + + +## 📊 Use Cases + + + +1. **Use Case 1**: +2. **Use Case 2**: +3. **Use Case 3**: + +## 🔗 Related Issues + + + +- Relates to # +- Blocks # +- Depends on # + +## Implementation Considerations + + + +### Breaking Changes + +- [ ] This feature would introduce breaking changes +- [ ] This feature is backward compatible + +### Dependencies + +- [ ] Requires new dependencies +- [ ] Uses existing dependencies only + +--- + +**Checklist** + +- [ ] I have searched existing issues to avoid duplicates +- [ ] I have provided a clear and detailed description +- [ ] I have explained the motivation and use cases +- [ ] I have considered the implementation approach +- [ ] I have thought about potential breaking changes diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7ce79c6..b21e545 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,7 +7,7 @@ It'll be great if relevant reviewers can be assigned as well.--> Please feel free to remove inapplicable items for your PR. -- [ ] The PR title starts with [$CATEGORY] (such as [Docs], [Fix], [Feature], [Refactor]) +- [ ] The PR title starts with `$CATEGORY(xx): xxx` (such as `feat(tool): xxx`, `fix(source): xxx`, `docs(README): xxx`) - [ ] Related issue is referred in this PR - [ ] The markdown and latex are rendered correctly. - [ ] The code in PR is well-documented. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf1afeb..014f892 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,183 +1,144 @@ # Contributing to QuantMind -Thank you for your interest in contributing to QuantMind! This guide outlines the best practices for contributing to our intelligent knowledge extraction framework for quantitative finance. +Thank you for contributing to QuantMind! This guide provides essential information for developers. -## Quick Start +## 🚀 Quick Setup 1. **Fork and clone** the repository -2. **Set up development environment**: - +2. **Set up environment**: ```bash - uv venv - source .venv/bin/activate + uv venv && source .venv/bin/activate uv pip install -e . ``` - 3. **Install pre-commit hooks**: - ```bash - # Automated setup (recommended) ./scripts/pre-commit-setup.sh - - # Or manual setup - pip install pre-commit - pre-commit install - pre-commit install --hook-type pre-push ``` -## Development Standards - -### Code Quality +## 🛠️ Development Setup -- **Location**: All new code must be in the `quantmind/` module -- **Style**: Google-style docstrings, 80-character line length -- **Architecture**: Use abstract base classes and dependency injection -- **Type Safety**: Comprehensive type hints with Pydantic models +### Pre-commit Hooks -### Testing Requirements +We use pre-commit hooks to ensure code quality and consistency. These hooks automatically format code, run linting, and perform other quality checks before each commit. -- **Unit tests**: Required for all new functionality in `tests/quantmind/` -- **Structure**: Mirror the `quantmind/` module structure -- **Coverage**: Test both success and error cases -- **Dependencies**: Mock external APIs and file systems +**Install pre-commit hooks:** -### Documentation - -- **Examples**: Add practical usage examples to `examples/quantmind/` -- **Comments**: Clear inline documentation for complex logic -- **Docstrings**: Google-style format for all public methods - -## Automated Quality Checks - -Our pre-commit configuration (`.pre-commit-config.yaml`) enforces quality standards: +```bash +# Automated setup (recommended) +./scripts/pre-commit-setup.sh -### On Every Commit +# Or manual setup +pip install pre-commit +pre-commit install +pre-commit install --hook-type pre-push +``` -- **Formatting**: `ruff format` (80-char line length) -- **Linting**: `ruff check --fix` (auto-fix issues) -- **File Quality**: Trailing whitespace, EOF, YAML syntax -- **Safety**: Check for large files and merge conflicts +**What the hooks do:** -### On Push to Remote +- **On every commit:** + - Code formatting with `ruff format` (80-char line length) + - Linting with `ruff check --fix` (auto-fixes issues) + - File quality checks (trailing whitespace, EOF, YAML syntax) + - Safety checks (large files, merge conflicts) -- **Unit Tests**: Full test suite via `scripts/unittest.sh` +- **On push to remote:** + - Full unit test suite via `scripts/unittest.sh` -### Manual Execution +**Manual execution:** ```bash # Run formatting and linting ./scripts/lint.sh +# Run all pre-commit hooks on all files +pre-commit run --all-files + # Run specific tests ./scripts/unittest.sh tests/quantmind/sources/ ./scripts/unittest.sh all # Run all tests ``` -## Contribution Types - -### 1. New Sources - -- Extend `BaseSource[ContentType]` in `quantmind/sources/` -- Add corresponding config in `quantmind/config/sources.py` -- Include comprehensive tests in `tests/sources/` -- Provide usage example in `examples/sources/` - -### 2. New Parsers +**Troubleshooting:** -- Extend `BaseParser` in `quantmind/parsers/` -- Handle multiple content formats -- Include error handling and validation -- Add tests for different input types +- If hooks fail, fix the issues and commit again +- To skip hooks temporarily (not recommended): `git commit --no-verify` +- Update hooks: `pre-commit autoupdate` -### 3. New Taggers +## 📝 Development Standards -- Extend `BaseTagger` in `quantmind/tagger/` -- Support both rule-based and ML-based approaches -- Include configuration options -- Test with various content types +### Code Requirements +- **Location**: All new code in `quantmind/` module +- **Style**: Google-style docstrings, 80-char line length +- **Architecture**: Abstract base classes + dependency injection +- **Type Safety**: Pydantic models + comprehensive type hints -### 4. Storage Backends +### Testing +- **Unit tests**: Required in `tests/quantmind/` (mirror module structure) +- **Coverage**: Test success and error cases +- **Mocking**: Mock external APIs and file systems -- Extend `BaseStorage` in `quantmind/storage/` -- Implement indexing and querying -- Handle concurrent access -- Include performance tests +### Documentation +- **Examples**: Add to `examples/quantmind/` for new features +- **Docstrings**: Google-style format for all public methods -## Code Quality Guidelines +## 🏗️ Contribution Types -### Architecture Principles +### New Sources +- Extend `BaseSource[ContentType]` in `quantmind/sources/` +- Add config in `quantmind/config/sources.py` +- Include tests and usage example -- **Separation of Concerns**: Single responsibility per component -- **Dependency Injection**: Configurable and testable components -- **Error Handling**: Comprehensive logging and graceful failures -- **Type Safety**: Use Pydantic models and type hints +### New Parsers +- Extend `BaseParser` in `quantmind/parsers/` +- Handle multiple content formats with error handling -### Best Practices +### New Taggers +- Extend `BaseTagger` in `quantmind/tagger/` +- Support rule-based and ML approaches -- Use existing utilities (`quantmind.utils.logger`) -- Follow the workflow orchestration pattern -- Implement proper configuration validation -- Add deduplication and quality control +### Storage Backends +- Extend `BaseStorage` in `quantmind/storage/` +- Implement indexing, querying, and concurrent access -## Pull Request Process +## 🔄 Pull Request Process 1. **Create feature branch** from `master` -2. **Implement changes** following development standards -3. **Pre-commit hooks will automatically**: - - Format code with `ruff format` - - Fix linting issues with `ruff check --fix` - - Validate file quality and syntax -4. **Before pushing**: - +2. **Follow conventional commits**: `type(scope): description` +3. **Pre-commit hooks** run automatically on commit/push +4. **Before submitting**: ```bash - # Verify all checks pass locally pre-commit run --all-files ./scripts/unittest.sh all ``` +5. **Submit PR** using our template -5. **Submit PR** with clear description and test plan - -### PR Requirements - -- [ ] Code in `quantmind/` module following architecture patterns -- [ ] Unit tests in `tests/` with comprehensive coverage -- [ ] Usage example in `examples/` (for new features) -- [ ] All pre-commit hooks pass (automatic on commit/push) -- [ ] Clear commit messages and PR description - -## Development Tips +### PR Checklist +- [ ] Code in `quantmind/` following architecture patterns +- [ ] Unit tests with comprehensive coverage +- [ ] Usage example (for new features) +- [ ] All pre-commit hooks pass +- [ ] Conventional commit format -### Testing +## 💡 Development Tips ```bash -# Run specific test modules +# Run specific tests pytest tests/quantmind/sources/ pytest tests/quantmind/models/ -# Run with coverage -pytest tests --cov=quantmind -``` - -### Local Development - -```bash # Test CLI functionality quantmind extract "test query" --max-papers 5 quantmind config show -``` - -### Configuration -- Use structured config via `quantmind.config.settings` -- Support environment variable overrides -- Provide sensible defaults -- Validate at startup +# Check code quality +./scripts/lint.sh +``` -## Questions? +## ❓ Questions? -- Check existing issues and discussions -- Follow the patterns in existing code +- Check existing [issues](https://github.com/LLMQuant/quant-mind/issues) +- Review architecture patterns in existing code - Look at `examples/` for usage patterns -- Review the architecture in `CLAUDE.md` +- See `CLAUDE.md` for detailed architecture -Thank you for contributing to QuantMind! 🚀 +Thank you for contributing! 🚀 diff --git a/README.md b/README.md index 246f9dc..c14d706 100644 --- a/README.md +++ b/README.md @@ -222,15 +222,28 @@ This future state represents our commitment to moving beyond simple data aggrega ### 🤝 Contributing -We welcome contributions of all forms, from bug reports to feature development. If you're interested in helping build the future of financial research, please review our contribution guidelines. For more details, please refer to [CONTRIBUTING.md](CONTRIBUTING.md). +We welcome contributions of all forms, from bug reports to feature development. -1. **Fork** the repository. -2. **Create a new branch** (`git checkout -b feature/my-new-feature`). -3. **Commit your changes** (`git commit -am 'Add some feature'`). -4. **Push to the branch** (`git push origin feature/my-new-feature`). -5. **Create a new Pull Request**. +> [!IMPORTANT] +> **For Contributors**: Please read [CONTRIBUTING.md](CONTRIBUTING.md) for essential development setup including pre-commit hooks, coding standards, and testing requirements. + +**Quick Start for Contributors:** -Please open an issue in the [GitHub Issues](https://github.com/LLMQuant/quant-mind/issues) tab to discuss any significant changes beforehand. +1. **Fork** the repository +2. **Setup development environment**: + ```bash + uv venv && source .venv/bin/activate + uv pip install -e . + ./scripts/pre-commit-setup.sh + ``` +3. **Create feature branch** (`git checkout -b feat/my-feature`) +4. **Follow conventional commits** (`feat: add new feature`) +5. **Submit PR** with our template + +**Before Contributing:** +- Open an [issue](https://github.com/LLMQuant/quant-mind/issues) to discuss significant changes +- Use our issue templates for bug reports and feature requests +- Ensure all pre-commit hooks pass before submitting PR ### License