Skip to content

Commit 2e8ea60

Browse files
DogInfantryDogInfantry
committed
chore: add CONTRIBUTING.md, ROADMAP.md, issue/PR templates, and fix requirements.txt
1 parent 6a5cb00 commit 2e8ea60

File tree

9 files changed

+600
-0
lines changed

9 files changed

+600
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: Bug Report
3+
about: Something is broken or producing wrong output
4+
title: '[BUG] '
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## 🐛 Describe the Bug
10+
11+
A clear, concise description of what went wrong.
12+
13+
## 📋 Steps to Reproduce
14+
15+
1. Run `python scripts/...`
16+
2. With these parameters / data / config: ...
17+
3. See error
18+
19+
## ✅ Expected Behaviour
20+
21+
What you expected to happen.
22+
23+
## ❌ Actual Behaviour
24+
25+
What actually happened. Paste the full traceback or error output below.
26+
27+
```
28+
# paste traceback here
29+
```
30+
31+
## 🌍 Environment
32+
33+
- OS: [e.g. macOS 14, Ubuntu 22.04, Windows 11]
34+
- Python version: [e.g. 3.13.0]
35+
- Key dependency versions (run `pip freeze | grep -E 'pandas|numpy|yfinance|plotly|scipy'`):
36+
37+
```
38+
# paste pip freeze output here
39+
```
40+
41+
## 📎 Additional Context
42+
43+
Any other context, screenshots, or sample data that helps reproduce the issue.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
name: Feature Request
3+
about: Propose a new model, data source, output format, or improvement
4+
title: '[FEAT] '
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## 💡 Summary
10+
11+
One-sentence description of the feature.
12+
13+
## 🎯 Motivation
14+
15+
Why would this improve the platform? Which vertical does it strengthen?
16+
- [ ] IPO Event Study
17+
- [ ] M&A Screening
18+
- [ ] Sovereign Risk
19+
- [ ] Cross-Asset Regime
20+
- [ ] Yield Curve
21+
- [ ] Infrastructure / DevEx
22+
- [ ] Output / Dashboards
23+
- [ ] Documentation
24+
25+
## 📐 Proposed Approach
26+
27+
Brief description of how you'd implement it. If it's an analytical model, cite your methodology source.
28+
29+
## 📦 Data Requirements
30+
31+
What data sources does this need? Is it already available in the repo, or does it need a new fetcher?
32+
33+
## 🔗 New Dependencies
34+
35+
Any new Python packages required? Are they zero-API-key compatible?
36+
37+
## 📎 References
38+
39+
Links to academic papers, practitioner notes, or existing open-source implementations.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
## 📝 What does this PR do?
2+
3+
Brief description of the change.
4+
5+
## 🔗 Related Issue
6+
7+
Closes #[issue number]
8+
9+
## 🔬 Type of Change
10+
11+
- [ ] Bug fix
12+
- [ ] New feature / model
13+
- [ ] Refactor (no behaviour change)
14+
- [ ] Docs / comments
15+
- [ ] Tests
16+
- [ ] Chore / dependency update
17+
18+
## ✅ How Was This Tested?
19+
20+
Describe how you validated the change:
21+
- [ ] Ran affected scripts end-to-end locally
22+
- [ ] Inspected output CSVs / dashboards / Excel / PDF
23+
- [ ] Added / updated pytest tests
24+
- [ ] Compared output to a known benchmark or reference value
25+
26+
## 📸 Sample Output (if applicable)
27+
28+
Paste a table of key numbers, or attach a screenshot of a dashboard/chart, so reviewers can eyeball correctness.
29+
30+
## 🚨 Breaking Changes?
31+
32+
- [ ] No breaking changes
33+
- [ ] Breaking change — describe what is affected and migration steps
34+
35+
## 📋 Checklist
36+
37+
- [ ] Code follows project style (`black` formatted, type hints on new functions)
38+
- [ ] `requirements.txt` updated if new dependencies added
39+
- [ ] README or docs updated if behaviour changes are user-visible
40+
- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)

‎.github/workflows/ci.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
lint-and-test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.10", "3.11", "3.13"]
15+
16+
steps:
17+
- name: Checkout code
18+
uses: actions/checkout@v4
19+
20+
- name: Set up Python ${{ matrix.python-version }}
21+
uses: actions/setup-python@v5
22+
with:
23+
python-version: ${{ matrix.python-version }}
24+
25+
- name: Cache pip dependencies
26+
uses: actions/cache@v4
27+
with:
28+
path: ~/.cache/pip
29+
key: ${{ runner.os }}-pip-${{ hashFiles('requirements*.txt') }}
30+
restore-keys: |
31+
${{ runner.os }}-pip-
32+
33+
- name: Install dependencies
34+
run: |
35+
python -m pip install --upgrade pip
36+
pip install -r requirements-dev.txt
37+
38+
- name: Lint with ruff
39+
run: ruff check scripts/ analysis/ --ignore E501
40+
continue-on-error: true
41+
42+
- name: Check formatting with black
43+
run: black --check scripts/ analysis/ --line-length 100
44+
continue-on-error: true
45+
46+
- name: Run tests
47+
run: |
48+
if [ -d tests ]; then pytest tests/ -v --tb=short; else echo "No tests directory yet — skipping"; fi

‎CONTRIBUTING.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Contributing to Capital Markets Intelligence Platform
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.
4+
5+
---
6+
7+
## 📋 Table of Contents
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)
16+
17+
---
18+
19+
## Getting Started
20+
21+
### 1. Fork & Clone
22+
23+
```bash
24+
git clone https://github.com/YOUR_USERNAME/capital-markets-intelligence.git
25+
cd capital-markets-intelligence
26+
```
27+
28+
### 2. Set Up Environment
29+
30+
Requires **Python 3.10+** (developed on 3.13).
31+
32+
```bash
33+
python -m venv venv
34+
source venv/bin/activate # Mac/Linux
35+
# venv\Scripts\activate # Windows
36+
pip install -r requirements.txt
37+
```
38+
39+
### 3. Run a Minimal Pipeline (Quick Validation)
40+
41+
You don't need to run all 13 scripts to test your changes. A fast subset:
42+
43+
```bash
44+
python scripts/01_fetch_ipo_data.py
45+
python scripts/05_fetch_sovereign_data.py
46+
python scripts/10_advanced_analysis.py
47+
python scripts/11_generate_plotly_dashboards.py
48+
```
49+
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.
71+
72+
### Commit Message Format
73+
74+
We follow [Conventional Commits](https://www.conventionalcommits.org/):
75+
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
83+
```
84+
85+
---
86+
87+
## Project Structure
88+
89+
```
90+
capital-markets-intelligence/
91+
├── scripts/ # Numbered 01–13 pipeline (data → analysis → outputs)
92+
├── 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+
```
105+
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.
107+
108+
---
109+
110+
## Coding Style
111+
112+
- **Formatter:** `black` (line length 100)
113+
- **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
118+
119+
To auto-format before committing:
120+
```bash
121+
pip install black ruff
122+
black scripts/ analysis/
123+
ruff check scripts/ analysis/
124+
```
125+
126+
---
127+
128+
## How to Propose Changes
129+
130+
### Bug Reports
131+
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
136+
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
142+
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
148+
149+
---
150+
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.
169+
170+
---
171+
172+
*Built to institutional research standards — contributions held to the same bar.*

0 commit comments

Comments
 (0)
⚡