mirror of
https://github.com/triqbit/mt5-ai-xauusd-trader.git
synced 2026-11-02 06:56:15 +00:00
docs: improve developer onboarding and contribution experience (#2152)
- Harmonize Contribution Map and Review Matrix across CONTRIBUTING.md, docs/CONTRIBUTING.md, docs/CONTRIBUTION_MAP.md, and docs/FIRST_REAL_CONTRIBUTION.md. - Update scripts/doctor.py (check_contribution_safety) to classify sensitive subsystems (src/research/, src/data/, src/environment/, main.py), utility subsystems (src/monitoring/), and explicit safe root templates (SETUP_GUIDE.md, .python-version). - Add verification unit tests in tests/test_doctor_diagnostics.py. 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>
This commit is contained in:
Leo
co-authored by
google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
triqbit
google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
triqbit
parent
76dc681c4a
commit
17c613c822
+112
-27
@@ -1,18 +1,19 @@
|
||||
# Contributing to MT5 AI/ML Trading Bot
|
||||
|
||||
To ensure the safety, reliability, and institutional grade of this trading system, all contributions must follow our established governance and workflow standards.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 Repository Status & Health
|
||||
## 🏛️ Governance Model
|
||||
|
||||
Our repository maintains high-quality standards and a clean, linear contribution path.
|
||||
We use a role-based governance model where specific leads oversee different domains. You can identify the required reviewers in [.github/CODEOWNERS](./.github/CODEOWNERS).
|
||||
|
||||
- **CI Success Rate:** 🟢 **PASSING** (All formatting, linting, and tests pass cleanly).
|
||||
- **Linear History:** 🟢 **STABLE** (The `main` branch maintains a fully linear, intact Git history for perfect auditability).
|
||||
- **PR Alignment:** Always keep your branch synchronized with the latest `main` commit.
|
||||
|
||||
We actively encourage and review Pull Requests in **Safe Zones** (docs, tests, scripts) to help onboard new developers smoothly.
|
||||
- **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.
|
||||
|
||||
---
|
||||
|
||||
@@ -29,40 +30,124 @@ Please refer to the following documents before opening a Pull Request:
|
||||
|
||||
## 🚦 System Safe Zones & Review Matrix
|
||||
|
||||
To help contributors start safely, system paths are categorized into clear review risk tiers:
|
||||
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` | 🟢 Low | Standard Peer Review | Yes (Documentation, Unit Tests, Developer Scripts) |
|
||||
| **Utility Zone** | `src/utils/`, `src/analytics/` | 🟡 Medium | Domain Lead Review | Secondary (Helpers, Telemetry, Analytics reports) |
|
||||
| **Sensitive Zone** | `src/trading/`, `src/models/`, `src/core/` | 🔴 High | Lead + Multi-Signature | No (Core Execution, Models, Risk Engine) |
|
||||
| **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) |
|
||||
|
||||
---
|
||||
|
||||
## 🚦 Quick Rules & Guidelines
|
||||
## 🚀 Contributor Workflow
|
||||
|
||||
- **Keep Aligned:** Always rebase or synchronize your branch with the latest `main` commit before submitting (`make resync`).
|
||||
- **PR Title & Branch Rules:** CI enforces semantic PR titles (`docs:`, `chore:`, `test:`, `fix:`, `feat:`, `perf:`, `style:`, `refactor:`, `ci:`). **Subject must start with a lowercase letter** (e.g., `docs: improve guide` NOT `docs: Improve guide`). **Do NOT use `DX:` prefix in PR titles or commits.**
|
||||
- **Safe Zone Focus:** New contributors are strongly advised to start in `docs/`, `tests/`, or `scripts/` for a fast, friction-free path to merge.
|
||||
- **Multi-Signature:** Changes to Sensitive Zones (`src/trading/`, `src/models/`, `src/core/`) require multi-signature approval from domain leads.
|
||||
- **Quality Gates:** All PRs must pass automated linting, type-checking, security scans, and maintain high test coverage.
|
||||
### 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](./docs/CONTRIBUTION_MAP.md):** 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, orchestration).
|
||||
|
||||
---
|
||||
### 🛠️ 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
|
||||
|
||||
To keep your feature branch seamlessly updated with the latest `main` commit, use this command:
|
||||
#### 🛠️ Synchronization Kit (CLI)
|
||||
To synchronize your branch with the latest `main` commit, run:
|
||||
|
||||
```bash
|
||||
# Automated sync with the latest main
|
||||
# Automated sync with latest main
|
||||
make resync
|
||||
```
|
||||
|
||||
If you ever need to perform a manual rebase:
|
||||
```bash
|
||||
# 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](https://www.conventionalcommits.org/) 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](./docs/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, 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).
|
||||
|
||||
---
|
||||
*This repository is maintained by a role-based governance team. See [CODEOWNERS](./.github/CODEOWNERS) for details.*
|
||||
|
||||
## 🛡️ 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](./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:
|
||||
```bash
|
||||
# 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](./SECURITY.md).
|
||||
- Report via **GitHub Private Vulnerability Reporting**.
|
||||
- For critical issues, contact the leads listed in `SECURITY.md`.
|
||||
|
||||
---
|
||||
|
||||
## 📖 Additional Resources
|
||||
- [Versioning Policy](./docs/VERSIONING_POLICY.md)
|
||||
- [Release Playbook](./docs/RELEASE_PLAYBOOK.md)
|
||||
- [SLO Targets](./docs/SLO_TARGETS.md)
|
||||
- [Architecture Quick-Start](./docs/ARCHITECTURE_QUICK.md)
|
||||
- [Enterprise Standards](./docs/ENTERPRISE_STANDARDS.md)
|
||||
|
||||
---
|
||||
*By contributing, you agree that your contributions will be licensed under the project's MIT License.*
|
||||
|
||||
+16
-2
@@ -22,7 +22,21 @@ We use a role-based governance model where specific leads oversee different doma
|
||||
### 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).
|
||||
- **Consult the [Contribution Map](./CONTRIBUTION_MAP.md):** 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:
|
||||
@@ -65,7 +79,7 @@ git rebase origin/main
|
||||
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).
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
@@ -6,9 +6,9 @@ This map defines the "Safe Zones" and "Sensitive Zones" of the MT5 AI/ML Trading
|
||||
|
||||
| Zone | Path | Risk Level | Review Requirement | Evidence Required |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **Safe Zone** | `docs/`, `tests/`, `scripts/`, `Makefile`, `.github/`, `.jules/`, `README.md`, `CONTRIBUTING.md`, `pyproject.toml`, `.gitignore`, `.env.example`, `.pre-commit-config.yaml`, `alembic.ini`, `SECURITY.md`, `DEVELOPMENT_PLAN.md`, `DATABASE_STANDARDS.md`, `DEPLOYMENT_GUIDE.md`, `RISK_LIMITS.md`, `TRADING_STANDARDS.md`, `ATTRIBUTIONS.md`, `CHANGELOG.md` | 🟢 Low | Standard Peer Review | Zero-Dep Unit Tests / Doc Lint |
|
||||
| **Utility Zone** | `src/utils/`, `src/analytics/` | 🟡 Medium | Domain Expert Review | Integration Tests |
|
||||
| **Sensitive Zone** | `src/trading/`, `src/models/`, `src/core/` | 🔴 High | Lead + Multi-Signature | Backtests + Stress Tests |
|
||||
| **Safe Zone** | `docs/`, `tests/`, `scripts/`, `Makefile`, `.github/`, `.jules/`, `README.md`, `CONTRIBUTING.md`, `pyproject.toml`, `.gitignore`, `.env.example`, `.pre-commit-config.yaml`, `alembic.ini`, `SECURITY.md`, `DEVELOPMENT_PLAN.md`, `DATABASE_STANDARDS.md`, `DEPLOYMENT_GUIDE.md`, `RISK_LIMITS.md`, `TRADING_STANDARDS.md`, `ATTRIBUTIONS.md`, `CHANGELOG.md`, `SETUP_GUIDE.md`, `.python-version` | 🟢 Low | Standard Peer Review | Zero-Dep Unit Tests / Doc Lint |
|
||||
| **Utility Zone** | `src/utils/`, `src/analytics/`, `src/monitoring/` | 🟡 Medium | Domain Expert Review | Integration Tests |
|
||||
| **Sensitive Zone** | `src/trading/`, `src/models/`, `src/core/`, `src/research/`, `src/data/`, `src/environment/`, `main.py` | 🔴 High | Lead + Multi-Signature | Backtests + Stress Tests |
|
||||
|
||||
---
|
||||
|
||||
@@ -50,8 +50,8 @@ These areas are perfect for new contributors to get familiar with the project an
|
||||
- **Improvement Areas:** Improving `make doctor` checks, `bootstrap.sh` robustness, GitHub Actions workflows, or adding new CLI helpers for developers.
|
||||
- **Goal:** Reduce the "Time to First Success" for new developers.
|
||||
|
||||
### 4. Root Safe Files (`README.md`, `CONTRIBUTING.md`, `pyproject.toml`, `.gitignore`, `.env.example`, `.pre-commit-config.yaml`, `alembic.ini`, `SECURITY.md`, `DEVELOPMENT_PLAN.md`, `DATABASE_STANDARDS.md`, `DEPLOYMENT_GUIDE.md`, `RISK_LIMITS.md`, `TRADING_STANDARDS.md`, `ATTRIBUTIONS.md`, `CHANGELOG.md`)
|
||||
- **Improvement Areas:** Documentation clarity, developer environment templates, database standards, and dependency management configs.
|
||||
### 4. Root Safe Files (`README.md`, `CONTRIBUTING.md`, `pyproject.toml`, `.gitignore`, `.env.example`, `.pre-commit-config.yaml`, `alembic.ini`, `SECURITY.md`, `DEVELOPMENT_PLAN.md`, `DATABASE_STANDARDS.md`, `DEPLOYMENT_GUIDE.md`, `RISK_LIMITS.md`, `TRADING_STANDARDS.md`, `ATTRIBUTIONS.md`, `CHANGELOG.md`, `SETUP_GUIDE.md`, `.python-version`)
|
||||
- **Improvement Areas:** Documentation clarity, developer environment templates, setup guides, runtime version declarations, database standards, and dependency management configs.
|
||||
- **Goal:** Clarify contributor instructions, environmental templates, and project metadata without touching production logic.
|
||||
|
||||
---
|
||||
@@ -83,6 +83,9 @@ These areas require a deeper understanding of the system's data structures but d
|
||||
### 2. Analytics (`src/analytics/`)
|
||||
- **Improvement Areas:** Post-trade analysis reports, visualization of backtest results, or journal mining logic.
|
||||
|
||||
### 3. Monitoring & Telemetry (`src/monitoring/`)
|
||||
- **Improvement Areas:** Grafana dashboard JSON configurations (`trading_overview.json`), telemetry metrics definitions, and health status indicators.
|
||||
|
||||
---
|
||||
|
||||
## 🔴 Sensitive Zones (High-Stake Areas)
|
||||
@@ -101,6 +104,22 @@ Changes to these directories affect the core financial and operational safety of
|
||||
- **Modules:** `config.py`, `health.py`, `constants.py`.
|
||||
- **Constraint:** Affects system-wide invariants and startup safety.
|
||||
|
||||
### 4. Quant Research & Simulation (`src/research/`)
|
||||
- **Modules:** `stress_lab.py`, `hyperopt_walkforward.py`, `rare_event_simulator.py`, `rl_evaluation.py`.
|
||||
- **Constraint:** Owned by Jules04; changes require quantitative evaluation metrics and validation of experimental realism.
|
||||
|
||||
### 5. Event Intelligence & Market Feeds (`src/data/`)
|
||||
- **Modules:** `event_intelligence.py`, `event_models.py`.
|
||||
- **Constraint:** Feeds real-time event signals into execution and feature pipelines.
|
||||
|
||||
### 6. Gym Simulation Environment (`src/environment/`)
|
||||
- **Modules:** `gym_env.py`.
|
||||
- **Constraint:** Core reinforcement learning simulation, state transitions, and reward penalties.
|
||||
|
||||
### 7. CLI Entrypoint & System Orchestration (`main.py`)
|
||||
- **Modules:** `main.py`.
|
||||
- **Constraint:** Central entrypoint for trading modes, CLI safety gates, and component lifecycle initialization.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ How to Pick Your First Task
|
||||
|
||||
@@ -176,7 +176,7 @@ Before submitting your PR:
|
||||
|
||||
1. **Branch Prefix:** Ensure your branch has a valid prefix (`docs/`, `chore/`, `feature/`, `bugfix/`, `hotfix/`, `refactor/`, `test/`, `ci/`, `perf/`, `style/`) matching your semantic PR title type.
|
||||
2. **Conventional Commits:** Commit your change with an approved semantic type (e.g., `chore: add workspace directory checks to doctor`).
|
||||
3. **Contributor Safety Audit:** Run `make doctor` (or `python3 scripts/doctor.py`) to execute automated Contributor Readiness checks (`Contribution Safety`, `Branch Naming`, `Graft Alignment`, `Git Configuration`). The `Contribution Safety` check automatically inspects modified files against Safe Zones (`docs/`, `tests/`, `scripts/`, `Makefile`) to verify you stay within low-risk contribution pathways.
|
||||
3. **Contributor Safety Audit:** Run `make doctor` (or `python3 scripts/doctor.py`) to execute automated Contributor Readiness checks (`Contribution Safety`, `Branch Naming`, `Graft Alignment`, `Git Configuration`). The `Contribution Safety` check automatically inspects modified files against Safe Zones (`docs/`, `tests/`, `scripts/`, `.github/`, `.jules/`, and explicit root safe files) to verify you stay within low-risk contribution pathways.
|
||||
4. **Run Governance Suite:** Run the project's governance validator to ensure all files match expectations:
|
||||
```bash
|
||||
PYTHONPATH=. python3 -m unittest tests/test_governance_vitals.py
|
||||
|
||||
+15
-3
@@ -618,7 +618,14 @@ def check_contribution_safety():
|
||||
files = list(all_files)
|
||||
|
||||
SAFE_ZONES = ["docs/", "tests/", "scripts/", ".github/", ".jules/"]
|
||||
SENSITIVE_ZONES = ["src/trading/", "src/models/", "src/core/"]
|
||||
SENSITIVE_ZONES = [
|
||||
"src/trading/",
|
||||
"src/models/",
|
||||
"src/core/",
|
||||
"src/research/",
|
||||
"src/data/",
|
||||
"src/environment/",
|
||||
]
|
||||
EXPLICIT_SAFE_FILES = [
|
||||
"Makefile",
|
||||
"README.md",
|
||||
@@ -636,6 +643,11 @@ def check_contribution_safety():
|
||||
"TRADING_STANDARDS.md",
|
||||
"ATTRIBUTIONS.md",
|
||||
"CHANGELOG.md",
|
||||
"SETUP_GUIDE.md",
|
||||
".python-version",
|
||||
]
|
||||
EXPLICIT_SENSITIVE_FILES = [
|
||||
"main.py",
|
||||
]
|
||||
|
||||
safe_files = []
|
||||
@@ -643,8 +655,8 @@ def check_contribution_safety():
|
||||
utility_files = []
|
||||
|
||||
for f in files:
|
||||
is_sensitive = any(f.startswith(z) for z in SENSITIVE_ZONES) or f in EXPLICIT_SENSITIVE_FILES
|
||||
is_safe = any(f.startswith(z) for z in SAFE_ZONES) or f in EXPLICIT_SAFE_FILES
|
||||
is_sensitive = any(f.startswith(z) for z in SENSITIVE_ZONES)
|
||||
|
||||
if is_sensitive:
|
||||
sensitive_files.append(f)
|
||||
@@ -658,7 +670,7 @@ def check_contribution_safety():
|
||||
"Contribution Safety",
|
||||
"WARNING",
|
||||
f"Sensitive zones touched ({len(sensitive_files)} files)",
|
||||
"Trading/Model logic requires multi-signature approval (Jules01/Jules03/Jules05).",
|
||||
"Trading/Model/Core logic requires multi-signature approval (Jules01/Jules03/Jules04/Jules05).",
|
||||
)
|
||||
elif utility_files:
|
||||
return DiagnosticCheck(
|
||||
|
||||
@@ -213,7 +213,10 @@ class TestDoctorDiagnostics(unittest.TestCase):
|
||||
|
||||
def test_check_contribution_safety_root_safe_files(self):
|
||||
"""Verify contribution safety check classifies root docs and setup templates as Safe Zone."""
|
||||
mock_diff = MagicMock(returncode=0, stdout=".env.example\nSECURITY.md\nDEVELOPMENT_PLAN.md\n")
|
||||
mock_diff = MagicMock(
|
||||
returncode=0,
|
||||
stdout=".env.example\nSECURITY.md\nDEVELOPMENT_PLAN.md\nSETUP_GUIDE.md\n.python-version\n",
|
||||
)
|
||||
mock_empty = MagicMock(returncode=0, stdout="")
|
||||
with patch("subprocess.run") as mock_run:
|
||||
mock_run.side_effect = [mock_diff, mock_empty, mock_empty]
|
||||
@@ -221,6 +224,33 @@ class TestDoctorDiagnostics(unittest.TestCase):
|
||||
self.assertEqual(res.status, "OK")
|
||||
self.assertIn("Safe zones touched", res.message)
|
||||
|
||||
def test_check_contribution_safety_sensitive_zones(self):
|
||||
"""Verify contribution safety check classifies research, data, environment, and main.py as Sensitive Zone."""
|
||||
mock_diff = MagicMock(
|
||||
returncode=0,
|
||||
stdout="src/research/hyperopt_walkforward.py\nsrc/data/event_intelligence.py\nsrc/environment/gym_env.py\nmain.py\n",
|
||||
)
|
||||
mock_empty = MagicMock(returncode=0, stdout="")
|
||||
with patch("subprocess.run") as mock_run:
|
||||
mock_run.side_effect = [mock_diff, mock_empty, mock_empty]
|
||||
res = doctor.check_contribution_safety()
|
||||
self.assertEqual(res.status, "WARNING")
|
||||
self.assertIn("Sensitive zones touched", res.message)
|
||||
self.assertIn("multi-signature approval", res.remedy)
|
||||
|
||||
def test_check_contribution_safety_utility_zones(self):
|
||||
"""Verify contribution safety check classifies monitoring, utils, and analytics as Utility Zone."""
|
||||
mock_diff = MagicMock(
|
||||
returncode=0,
|
||||
stdout="src/monitoring/dashboards/trading_overview.json\nsrc/utils/security.py\nsrc/analytics/execution_quality.py\n",
|
||||
)
|
||||
mock_empty = MagicMock(returncode=0, stdout="")
|
||||
with patch("subprocess.run") as mock_run:
|
||||
mock_run.side_effect = [mock_diff, mock_empty, mock_empty]
|
||||
res = doctor.check_contribution_safety()
|
||||
self.assertEqual(res.status, "OK")
|
||||
self.assertIn("Utility zones touched", res.message)
|
||||
|
||||
def test_get_triage_top_items(self):
|
||||
"""Verify triage scraping logic."""
|
||||
mock_content = """
|
||||
|
||||
Reference in New Issue
Block a user