Contributing to EasyQuant¶
Thanks for your interest in contributing to EasyQuant. We welcome bug reports, feature requests, documentation improvements, and code.
How to Contribute¶
Report Bugs¶
Use GitHub Issues to report bugs. Please include:
- A clear description of the bug
- Steps to reproduce (minimal example if possible)
- Expected vs. actual behavior
- Python version and
eqlibversion - Relevant log output or error messages
Suggest Features¶
Open a GitHub Issue to discuss new features before submitting a PR. This helps us align on scope and design.
Submit Pull Requests¶
- Fork the repo and create a feature branch (
git checkout -b feature/my-feature) - Make your changes — follow the existing code style
- Add or update tests in
tests/for any code changes - Run the test suite:
python -m pytest tests/ - Commit with a conventional prefix (see below)
- Push and open a PR against
main
Development Setup¶
Code Style¶
- Follow PEP 8 conventions; use type hints
- Keep imports explicit — avoid
from eqlib import *in examples - Add docstrings for public API functions
- Mark exports in
eqlib/__init__.pyasSTABLE,EXPERIMENTAL, orDEPRECATED - Use the shared constants in
eqlib/constants.py(RISK_FREE_RATE = 0.03,TRADING_DAYS_PER_YEAR = 244) instead of hardcoding - Pre-commit hooks enforce trailing whitespace, EOF fixes, and YAML/TOML validation
Documentation¶
The docs live in docs/ and are bilingual: every *.md file has an English *.en.md sibling.
- When you edit
docs/**/*.md, update the matching.en.mdin the same PR - Run
python scripts/check_doc_sync.pybefore committing — it checks translation pairing, stale example references, and that trading-cost figures matchexamples/_defaults.py - CI runs
mkdocs build --strict; you can verify locally withmkdocs serve - Public API changes in
eqlib/require updating affected examples, the tutorial docs (both languages), anddocs/reference/
Examples¶
When adding or modifying examples under examples/:
- Use
examples/_defaults.pyfor trading costs and stock codes (stamp duty 0.05%, commission 0.025%, minimum 5 CNY) - Include a module docstring with number, title, description, and teaching objectives
- Add an
if __name__ == "__main__":guard - Update both example indices:
examples/README.mdanddocs/examples/index.md(plus its.en.md)
Commit Messages¶
Use conventional prefixes:
| Prefix | Use for |
|---|---|
docs: |
Documentation (always update both .md and .en.md) |
fix: |
Bug fixes |
feat: |
New features or examples |
chore: |
Cleanup, reorganization |
refactor: |
Code restructuring without behavior change |
License¶
By contributing, you agree that your contributions will be licensed under the MIT License.