mirror of
https://github.com/triqbit/mt5-ai-xauusd-trader.git
synced 2026-11-02 06:56:15 +00:00
3c110f7f22
Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> Co-authored-by: triqbit <242833443+triqbit@users.noreply.github.com>
127 lines
6.6 KiB
Markdown
127 lines
6.6 KiB
Markdown
# Contributing to MT5 AI/ML Trading Bot
|
|
|
|
Thank you for your interest in contributing! As an institutional-grade trading system, we maintain high standards for code quality, safety, and reliability. This project follows an enterprise-grade governance model to ensure every change is verified, auditable, and production-safe.
|
|
|
|
---
|
|
|
|
## 🏛️ Governance Model
|
|
|
|
We use a role-based governance model where specific leads oversee different domains. You can identify the required reviewers in [.github/CODEOWNERS](../.github/CODEOWNERS).
|
|
|
|
- **Jules01 (Core & Trading) — `@triqbit`:** Oversees core architecture, MT5/XAUUSD trading logic, and system performance.
|
|
- **Jules02 (Security & Quality) — `@xnessom`:** Manages security, validation, CI quality, and system observability.
|
|
- **Jules03 (Release & Reliability) — `@andonly1348`:** Oversees release reliability, enterprise delivery, and governance compliance.
|
|
- **Jules04 (Quant & Research) — `@saysgrok`:** Responsible for model architectures, adaptive intelligence, and research simulations.
|
|
- **Jules05 (Product & Integration) — `@yxynoty`:** Oversees product stewardship, integration governance, and feature portfolio.
|
|
- **Jules06 (Developer Experience) — `@qufuwan`:** Owns the safe contribution pathway, developer runtime, and technical credibility.
|
|
|
|
---
|
|
|
|
## 🚀 Contributor Workflow
|
|
|
|
### 1. Preparation
|
|
- **Fork and Clone:** Create your own fork and clone it locally.
|
|
- **Setup Environment:** Use Python 3.11+. Follow the [Setup Guide](../SETUP_GUIDE.md).
|
|
- **Consult the [Contribution Map](./CONTRIBUTION_MAP.md):** Identify if your change falls into a **Safe Zone** (docs, tests) or a **Sensitive Zone** (trading logic, models, core).
|
|
|
|
### 🛠️ Git Workflow & Synchronization
|
|
This repository maintains a **100% linear, stable, and intact Git history** on `main`. To keep your pull request clean and easy to review:
|
|
- **Linear History:** The `main` branch maintains a complete linear history tracing back to the repository's root.
|
|
- **Branch Synchronization:** Keep your feature branch synchronized with `main` before submitting your PR. Use `make resync` for an automated sync.
|
|
- **Environment Stability:** If `make bootstrap` fails, check `docs/status/PROJECT_HEALTH.md` for known dependency conflicts or transient environment issues.
|
|
|
|
#### 🛠️ Synchronization Kit (CLI)
|
|
To synchronize your branch with the latest `main` commit, run:
|
|
|
|
```bash
|
|
# Automated sync with latest main
|
|
make resync
|
|
|
|
# Or manually rebase against main:
|
|
git fetch origin main
|
|
git rebase origin/main
|
|
```
|
|
|
|
### 2. Implementation
|
|
- **Branching Strategy:** We enforce a strict branching strategy to ensure traceability. All development must occur on branches prefixed by type:
|
|
- `feature/`: New capabilities or enhancements (e.g., `feature/ppo-optim-v2`)
|
|
- `bugfix/`: Fixes for identified issues (e.g., `bugfix/mt5-conn-leak`)
|
|
- `hotfix/`: Emergency production patches directly against `main`
|
|
- `docs/`: Documentation-only improvements
|
|
- `refactor/`: Code reorganization without functional changes
|
|
- `chore/`: Tasks and developer tools checks (e.g., `chore/add-doctor-checks`)
|
|
- `test/`: Adding or updating tests (e.g., `test/doctor-coverage`)
|
|
- `ci/`: Developer workflow and CI configurations (e.g., `ci/harden-checks`)
|
|
- `perf/`: Performance optimization changes (e.g., `perf/vectorize-sma`)
|
|
- `style/`: Non-functional style, formatting, or lint-only fixes (e.g., `style: run-ruff-formatter`)
|
|
- **Conventional Commits:** All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification (e.g., `feat:`, `fix:`, `docs:`, `chore:`, `security:`). This enables automated changelog generation and versioning.
|
|
- **Standards:** Adhere to [ENTERPRISE_STANDARDS.md](./ENTERPRISE_STANDARDS.md) for linting, typing, and documentation.
|
|
|
|
### 3. Pull Request Lifecycle
|
|
1. **Draft PR:** Open a Draft PR early to get feedback on architectural direction.
|
|
2. **Mandatory Checks:** Ensure your PR passes all automated CI gates (Lint, Type, Security, Tests).
|
|
3. **Governance Template:** Complete the [.github/PULL_REQUEST_TEMPLATE.md](../.github/PULL_REQUEST_TEMPLATE.md) in full.
|
|
4. **Evidence:** Attach test logs, coverage reports, and backtest evidence.
|
|
5. **Review Cycle:** At least one approval from a designated [CODEOWNER](../.github/CODEOWNERS) is required.
|
|
6. **Multi-Signature Sign-off:** Changes to **Sensitive Zones** (Trading, Models, Core) require mandatory multi-signature approval from both the relevant domain lead and the Release/Governance lead (@andonly1348).
|
|
7. **Merge:** Once all criteria are met, the branch is merged into `main` (or `develop` if applicable).
|
|
|
|
---
|
|
|
|
## 🛡️ Required PR Checks (Mandatory Quality Gates)
|
|
|
|
Every Pull Request must pass the following gates before merge:
|
|
|
|
1. **CI Pipeline:** Must pass all automated checks in GitHub Actions.
|
|
2. **Code Coverage:** Minimum **85%** statement coverage. New code must include unit tests.
|
|
3. **Type Safety:** `mypy` must return zero errors for all modified files.
|
|
4. **Linting:** `ruff check .` must return zero errors.
|
|
5. **Security Scan:** `pip-audit` or `trivy` must show zero vulnerabilities in dependencies.
|
|
6. **License Compliance:** All new dependencies must comply with [docs/LICENSE_COMPLIANCE.md](./LICENSE_COMPLIANCE.md).
|
|
7. **Documentation:** Documentation in `docs/` must be updated to reflect any source code changes.
|
|
|
|
---
|
|
|
|
## 🧪 Testing & Governance Verification
|
|
|
|
We practice Test-Driven Development (TDD) where possible.
|
|
- **Unit Tests:** Mandatory for all new functions and classes.
|
|
- **Integration Tests:** Required for changes touching MT5 connectors or database schemas.
|
|
- **Resilience Tests:** Mandatory for risk-management logic.
|
|
|
|
Run the full suite and governance checks locally:
|
|
```bash
|
|
# Run tests with coverage
|
|
PYTHONPATH=. python3 -m pytest tests/ --cov=src --cov-report=term-missing
|
|
|
|
# Run governance vitals check
|
|
PYTHONPATH=. python3 -m pytest tests/test_governance_vitals.py --noconftest
|
|
|
|
# Run Atlas Governance Auditor
|
|
python3 scripts/atlas_audit.py
|
|
|
|
# Run environment diagnostics
|
|
python3 scripts/doctor.py
|
|
```
|
|
|
|
---
|
|
|
|
## 🛡️ Security First
|
|
|
|
If you discover a security vulnerability, please **do NOT open a public issue**.
|
|
- Follow the [Security Policy](../SECURITY.md).
|
|
- Report via **GitHub Private Vulnerability Reporting**.
|
|
- For critical issues, contact the leads listed in `SECURITY.md`.
|
|
|
|
---
|
|
|
|
## 📖 Additional Resources
|
|
- [Versioning Policy](./VERSIONING_POLICY.md)
|
|
- [Release Playbook](./RELEASE_PLAYBOOK.md)
|
|
- [SLO Targets](./SLO_TARGETS.md)
|
|
- [Architecture Quick-Start](./ARCHITECTURE_QUICK.md)
|
|
- [Enterprise Standards](./ENTERPRISE_STANDARDS.md)
|
|
|
|
---
|
|
*By contributing, you agree that your contributions will be licensed under the project's MIT License.*
|