You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Contributing to Capital Markets Intelligence Platform
2
2
3
-
Thank you for your interest in contributing! This project is open to contributions from anyone with an interest in quantitative finance, data engineering, or Python development.
3
+
Thank you for your interest in contributing! This platform is built to mirror institutional research standards — contributions that raise analytical depth, code quality, or usability are all welcome.
4
4
5
5
---
6
6
7
-
## 📋 Table of Contents
7
+
## Table of Contents
8
8
9
-
-[Getting Started](#getting-started)
10
-
-[Development Workflow](#development-workflow)
11
-
-[Project Structure](#project-structure)
12
-
-[Coding Style](#coding-style)
13
-
-[How to Propose Changes](#how-to-propose-changes)
14
-
-[Good First Issues](#good-first-issues)
15
-
-[Need Help?](#need-help)
9
+
1.[Getting Started](#getting-started)
10
+
2.[Development Setup](#development-setup)
11
+
3.[Running the Pipeline](#running-the-pipeline)
12
+
4.[How to Contribute](#how-to-contribute)
13
+
5.[Coding Style](#coding-style)
14
+
6.[Submitting a PR](#submitting-a-pr)
15
+
7.[Issue Labels](#issue-labels)
16
16
17
17
---
18
18
19
19
## Getting Started
20
20
21
-
### 1. Fork & Clone
21
+
1.**Fork** the repository and clone your fork locally.
22
+
2. Browse [open issues](../../issues) — look for `good first issue` or `help wanted` labels.
23
+
3. Comment on an issue to claim it before starting work.
You don't need to run all 13 scripts to test your changes. A fast subset:
47
+
## Running the Pipeline
42
48
49
+
**Quick validation** (minimal run — recommended for contributors):
43
50
```bash
44
51
python scripts/01_fetch_ipo_data.py
45
52
python scripts/05_fetch_sovereign_data.py
46
53
python scripts/10_advanced_analysis.py
47
54
python scripts/11_generate_plotly_dashboards.py
48
55
```
49
56
50
-
### 4. Verify Outputs
51
-
52
-
After running, check that:
53
-
-`data/processed/` contains updated CSVs
54
-
-`output/dashboards/` contains `.html` files you can open in a browser
55
-
56
-
---
57
-
58
-
## Development Workflow
59
-
60
-
1.**Find or open an issue** — check the [Issues](https://github.com/DogInfantry/capital-markets-intelligence/issues) tab. Look for `good first issue` or `help wanted` labels.
61
-
2.**Comment on the issue** to say you're working on it (avoids duplicate work).
62
-
3.**Create a branch** from `main`:
63
-
```bash
64
-
git checkout -b feature/your-feature-name
65
-
# or
66
-
git checkout -b fix/your-bug-fix
67
-
```
68
-
4.**Make your changes**, commit with clear messages (see below).
69
-
5.**Open a Pull Request** against `main` using the PR template.
70
-
6.**Respond to review** — we aim to review PRs within 48–72 hours.
57
+
**Full pipeline:**
58
+
```bash
59
+
# Phase 1 — Data Collection
60
+
python scripts/01_fetch_ipo_data.py
61
+
python scripts/02_fetch_mna_data.py
62
+
python scripts/03_stress_test_model.py
63
+
python scripts/04_case_study_builder.py
64
+
python scripts/05_fetch_sovereign_data.py
71
65
72
-
### Commit Message Format
66
+
# Phase 2 — Live API Data
67
+
python scripts/08_fetch_fred_data.py
68
+
python scripts/09_fetch_worldbank_data.py
73
69
74
-
We follow [Conventional Commits](https://www.conventionalcommits.org/):
70
+
# Phase 3 — Advanced Analysis
71
+
python scripts/10_advanced_analysis.py
75
72
76
-
```
77
-
feat: add logistic regression to M&A deal screening
78
-
fix: handle missing yield curve data for short-dated tenors
79
-
docs: add Scenario Cookbook for IPO event study
80
-
refactor: extract CSV loading helpers to utils module
81
-
test: add golden-data test for sovereign risk index
82
-
chore: update requirements.txt with yfinance and plotly
73
+
# Phase 4 — Outputs
74
+
python scripts/06_generate_visualizations.py
75
+
python scripts/07_generate_memos.py
76
+
python scripts/11_generate_plotly_dashboards.py
77
+
python scripts/12_generate_excel_reports.py
78
+
python scripts/13_generate_pdf_reports.py
83
79
```
84
80
85
-
---
81
+
Outputs appear in `output/` (dashboards, Excel, PDFs, memos).
├── analysis/ # Jupyter notebooks for exploratory work
93
-
├── data/
94
-
│ ├── raw/ # Live API + curated source data
95
-
│ ├── processed/ # Model output CSVs (generated, not tracked)
96
-
│ └── cache/ # API response cache (not tracked)
97
-
├── output/
98
-
│ ├── dashboards/ # Plotly HTML files
99
-
│ ├── excel/ # openpyxl workbooks
100
-
│ ├── pdf/ # fpdf reports
101
-
│ └── memos/ # Text research memos
102
-
├── docs/ # Extended documentation
103
-
└── tests/ # (Planned) pytest test suite
104
-
```
85
+
## How to Contribute
105
86
106
-
**Key principle:** Scripts are numbered in execution order. Each script reads from `data/` and writes back to `data/processed/` or `output/`. Avoid cross-script imports — each script should be independently runnable.
87
+
1. Pick an issue or open a new one describing your idea.
88
+
2. Create a feature branch: `git checkout -b feature/your-feature-name`
89
+
3. Make your changes (keep PRs focused — one feature or fix per PR).
90
+
4. Run the quick validation pipeline to confirm nothing is broken.
91
+
5. Commit with a clear message: `feat: add sector-level M&A summaries`
92
+
6. Push and open a Pull Request against `main`.
107
93
108
94
---
109
95
110
96
## Coding Style
111
97
112
98
-**Formatter:**`black` (line length 100)
113
99
-**Linter:**`ruff` or `flake8`
114
-
-**Docstrings:** Google-style
115
-
-**Type hints:**Encouraged for new functions, required for any new shared utilities
116
-
-**No hard-coded paths:**Use `pathlib.Path(__file__).parent` for relative paths
117
-
-**No silent failures:**Raise meaningful exceptions or print a clear warning when data is unavailable
100
+
-**Docstrings:**NumPy or Googlestyle
101
+
-**Paths:**use `pathlib.Path`, not raw string concatenation
102
+
-**Logging:**use Python `logging` module, not `print()`
Open an issue using the **Bug Report** template. Include:
132
-
- Steps to reproduce
133
-
- Expected vs actual behaviour
134
-
- Python version, OS, and dependency versions (`pip freeze`)
135
-
- Any relevant log output or tracebacks
114
+
## Submitting a PR
136
115
137
-
### Feature Requests
138
-
Open an issue using the **Feature Request** template. Include:
139
-
- Why this improves the platform (which use case / vertical does it help?)
140
-
- What data sources it needs
141
-
- Whether it requires new dependencies
116
+
Please fill in the PR template when opening a PR. Key points:
142
117
143
-
### Analytics / Model PRs
144
-
If your PR changes an analytical model (e.g., event study methodology, sovereign risk weights):
145
-
- Include a short write-up (in the PR body or a `docs/` file) explaining the methodology and its source
146
-
- Show sample output before and after
147
-
- Link to any academic papers or practitioner references used
118
+
- What changed and why.
119
+
- How you tested it (e.g., "ran quick validation, checked Excel output").
120
+
- Screenshots or sample output if the change touches dashboards/reports.
148
121
149
122
---
150
123
151
-
## Good First Issues
152
-
153
-
Looking for somewhere to start? These are well-scoped entry points:
154
-
155
-
- 🏷️ Filter by [`good first issue`](https://github.com/DogInfantry/capital-markets-intelligence/issues?q=is%3Aopen+label%3A%22good+first+issue%22)
156
-
- 🏷️ Filter by [`help wanted`](https://github.com/DogInfantry/capital-markets-intelligence/issues?q=is%3Aopen+label%3A%22help+wanted%22)
157
-
158
-
Examples of good first contributions:
159
-
- Fix a typo or improve an explanation in the README
160
-
- Add a missing dependency to `requirements.txt`
161
-
- Add type hints to one script
162
-
- Write a pytest test for a single model function
163
-
164
-
---
165
-
166
-
## Need Help?
167
-
168
-
Open a [Discussion](https://github.com/DogInfantry/capital-markets-intelligence/discussions) or tag `@DogInfantry` in an issue comment. We're happy to help you get oriented.
124
+
## Issue Labels
125
+
126
+
| Label | Meaning |
127
+
|-------|---------|
128
+
|`good first issue`| Small, well-scoped — great for new contributors |
129
+
|`help wanted`| Higher-impact work the maintainer wants community help on |
130
+
|`analytics`| Changes to quantitative models or analysis logic |
131
+
|`data`| Changes to data fetching, cleaning, or schemas |
0 commit comments