mt5-ai-xauusd-trader/docs/CONTRIBUTING.md

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.

• 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.
• Consult the Contribution Map: Identify if your change falls into a Safe Zone (docs, tests, scripts), Utility Zone (utils, analytics, monitoring), or Sensitive Zone (trading logic, models, core, research, data, environment).

---

🚦 System Safe Zones & Review Matrix

To help contributors start safely, repository paths are categorized into clear review risk tiers:

Zone	Path	Risk Level	Review Requirement	Recommended First Contribution
Safe Zone	docs/, tests/, scripts/, Makefile, .github/, .jules/, root safe docs/configs	🟢 Low	Standard Peer Review	Yes (Documentation, Unit Tests, Developer Scripts)
Utility Zone	src/utils/, src/analytics/, src/monitoring/	🟡 Medium	Domain Lead Review	Secondary (Helpers, Telemetry, Analytics reports)
Sensitive Zone	src/trading/, src/models/, src/core/, src/research/, src/data/, src/environment/, main.py	🔴 High	Lead + Multi-Signature	No (Core Execution, Models, Risk Engine, Simulation)

---

🛠️ 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:

# 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 and PR titles must follow the Conventional Commits specification (e.g., feat:, fix:, docs:, chore:, test:, refactor:, style:, perf:, ci:). This enables automated changelog generation and versioning.
  • PR Title Casing: The subject after the prefix must start with a lowercase letter (e.g., docs: improve developer guide NOT docs: Improve developer guide).
  • Notice on DX Prefix: Do NOT use non-standard prefixes like DX: in PR titles or commits; use docs: for documentation/onboarding PRs or chore: for DX tool scripts.
• Standards: Adhere to 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 in full.
4. Evidence: Attach test logs, coverage reports, and backtest evidence.
5. Review Cycle: At least one approval from a designated CODEOWNER is required.
6. Multi-Signature Sign-off: Changes to Sensitive Zones (Trading, Models, Core, Research, Data, Environment, CLI Orchestration) 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.
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:

# Run tests with coverage
PYTHONPATH=. python3 -m pytest tests/ --cov=src --cov-report=term-missing

# Run governance vitals check (zero-dependency via unittest or pytest)
PYTHONPATH=. python3 -m unittest tests/test_governance_vitals.py
# Or via pytest:
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.
• Report via GitHub Private Vulnerability Reporting.
• For critical issues, contact the leads listed in SECURITY.md.

---

📖 Additional Resources

• Versioning Policy
• Release Playbook
• SLO Targets
• Architecture Quick-Start
• Enterprise Standards

---

By contributing, you agree that your contributions will be licensed under the project's MIT License.