Skip to content

Commit a4c3adb

Browse files
Copilotbenoit-ctybenoit-ctyinimaz
authored
Add Copilot instructions to help navigate CodeCarbon repository (#884)
* Initial plan * Add comprehensive Copilot instructions for CodeCarbon repository Co-authored-by: benoit-cty <6603048+benoit-cty@users.noreply.github.com> * Change to dashboard * Update Copilot instructions to use uv instead of hatch Co-authored-by: inimaz <49730431+inimaz@users.noreply.github.com> * doc --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: benoit-cty <6603048+benoit-cty@users.noreply.github.com> Co-authored-by: benoit-cty <benoit-cty@leximpact.dev> Co-authored-by: inimaz <49730431+inimaz@users.noreply.github.com>
1 parent b8550b0 commit a4c3adb

1 file changed

Lines changed: 198 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# CodeCarbon Copilot Instructions
2+
3+
This repository contains multiple components for tracking CO2 emissions from computing.
4+
5+
CodeCarbon works by measuring electricity consumption on the computer and convert it to CO2 emissions using electricity carbon intensity from the grid where the computer is located.
6+
7+
It's a mono-repo for a Python package, a centralized API and an online dashboard.
8+
9+
The package also have a command line to monitor computer's emissions without wrinting Python code.
10+
11+
Here's what you need to know to navigate and contribute effectively.
12+
13+
## Repository Structure
14+
15+
### Main Components
16+
17+
1. **📦 codecarbon/** - Core Python package
18+
- Main library for tracking carbon emissions
19+
- CLI tools and utilities
20+
- Core emission tracking functionality
21+
22+
2. **🔌 carbonserver/** - API Backend
23+
- FastAPI-based REST API
24+
- PostgreSQL database integration
25+
- User management and data persistence
26+
- Run with: `uv run task docker` or `uv run task dashboard`
27+
28+
3. **📊 dashboard/viz** - Python Dashboard (Dash-based)
29+
- Interactive dashboard using Dash/Plotly
30+
- Visualizes emission data from CSV files
31+
- Run with: `uv run task carbonboard`
32+
33+
4. **🌐 webapp/** - Next.js Web Dashboard
34+
- Modern React/Next.js web application
35+
- Connects to the API backend
36+
- Run with: `cd webapp && pnpm dev`
37+
38+
### Key Directories
39+
40+
- **tests/** - Unit tests for the core package
41+
- **docs/** - Sphinx documentation (build with `uv run task docs`)
42+
- **examples/** - Usage examples and demos
43+
- **deploy/** - Deployment configurations and scripts
44+
- **requirements/** - Dependency specifications for different environments
45+
46+
## Development Setup
47+
48+
### Prerequisites
49+
- Python 3.7+ (preferably 3.11+)
50+
- uv (Python project manager): `curl -LsSf https://astral.sh/uv/install.sh | sh`
51+
- Node.js & pnpm (for webapp): `npm install -g pnpm` or `curl -fsSL https://get.pnpm.io/install.sh | sh -`
52+
- Docker (for API development)
53+
54+
### Quick Start
55+
56+
1. **Core Package Development:**
57+
```bash
58+
# Run tests
59+
uv run task test-package
60+
61+
# Run specific test
62+
uv run pytest tests/test_emissions_tracker.py
63+
64+
# Lint and format
65+
uv run task lint
66+
uv run task format
67+
```
68+
69+
2. **API Development:**
70+
```bash
71+
# Start API with Docker (recommended)
72+
uv run task docker
73+
74+
# Or run locally (requires PostgreSQL setup)
75+
uv run task dashboard
76+
77+
# Test API
78+
uv run task test-api-unit
79+
uv run task test-api-integ
80+
```
81+
82+
3. **Dashboard Development:**
83+
```bash
84+
# Python dashboard
85+
uv run task carbonboard
86+
87+
# Next.js webapp
88+
cd webapp
89+
pnpm install
90+
pnpm dev
91+
```
92+
93+
## Testing Strategy
94+
95+
### Core Package Tests
96+
- **Unit tests**: `tests/test_*.py` - Test individual components
97+
- **Integration tests**: Include real hardware testing with `CODECARBON_ALLOW_MULTIPLE_RUNS=True`
98+
- **Run specific tests**: `uv run pytest tests/test_specific.py`
99+
100+
### API Tests
101+
- **Unit tests**: `uv run task test-api-unit` - Test business logic
102+
- **Integration tests**: `uv run task test-api-integ` - Test with database
103+
- **See**: `carbonserver/tests/TESTING.md` for detailed testing guide
104+
105+
### Manual Testing
106+
- **Stress testing**: Use `7z b` for CPU or gpu-burn for GPU testing
107+
- **CLI testing**: Use examples in `examples/` directory
108+
- **Monitor with**: `nvidia-smi` for GPU metrics comparison
109+
110+
## Common Development Patterns
111+
112+
### Adding New Features
113+
1. **Check existing tests** in `tests/` for similar functionality
114+
2. **Add unit tests** first (test-driven development)
115+
3. **Update documentation** if public interface changes
116+
4. **Follow coding style**: Use `uv run task format` and `uv run task lint`
117+
118+
### API Development
119+
1. **Follow FastAPI patterns** - see routers in `carbonserver/carbonserver/api/routers/`
120+
2. **Use dependency injection** - see `carbonserver/container.py`
121+
3. **Database migrations** - use Alembic (see `carbonserver/carbonserver/database/alembic/`)
122+
4. **Test with Postman** - collection in `carbonserver/tests/postman/`
123+
124+
### Dashboard Development
125+
1. **Python Dashboard**: Uses Dash + Plotly, see `codecarbon/viz`
126+
2. **Next.js Dashboard**: Modern React components in `webapp/src/`
127+
3. **Connect to API**: Set `CODECARBON_API_URL=http://localhost:8008` for local development
128+
129+
## Environment Management
130+
131+
### UV Task Management
132+
```bash
133+
# List all available tasks
134+
uv run task -l
135+
136+
# Main tasks:
137+
# - test-package: Core package testing
138+
# - lint: Code linting and style checks
139+
# - format: Code formatting
140+
# - test-api-unit: API unit tests
141+
# - test-api-integ: API integration tests
142+
# - dashboard: Run API locally
143+
# - docker: Start API with Docker
144+
# - carbonboard: Python dashboard
145+
# - docs: Build documentation
146+
```
147+
148+
### Configuration Files
149+
- **pyproject.toml**: Main project configuration
150+
- **.codecarbon.config**: Runtime configuration for API connection
151+
- **docker-compose.yml**: Local development with PostgreSQL
152+
- **requirements/**: Pinned dependencies for different environments
153+
154+
## Documentation and Help
155+
156+
### Key Documentation Files
157+
- **[CONTRIBUTING.md](CONTRIBUTING.md)**: Detailed contribution guidelines and setup
158+
- **[README.md](README.md)**: Project overview and quickstart
159+
- **[carbonserver/README.md](carbonserver/README.md)**: API architecture and database schema
160+
- **[webapp/README.md](webapp/README.md)**: Next.js dashboard setup
161+
- **[carbonserver/tests/TESTING.md](carbonserver/tests/TESTING.md)**: Comprehensive testing guide
162+
163+
### VS Code Debugging
164+
The repository includes VS Code launch configurations in CONTRIBUTING.md for:
165+
- Debugging current Python file
166+
- Running pytest with debugger
167+
- Testing codecarbon CLI monitor
168+
169+
### Getting Help
170+
- **FAQ**: https://mlco2.github.io/codecarbon/faq.html
171+
- **Documentation**: https://mlco2.github.io/codecarbon/
172+
- **Issues**: https://github.com/mlco2/codecarbon/issues
173+
174+
## Architecture Overview
175+
176+
```
177+
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
178+
│ codecarbon │ │ carbonserver │ │ dashboards │
179+
│ (package) │───▶│ (API) │◀───│ (2 versions) │
180+
│ │ │ │ │ │
181+
│ • CLI tools │ │ • FastAPI │ │ • Dash (Python) │
182+
│ • Tracking core │ │ • PostgreSQL │ │ • Next.js (Web) │
183+
│ • Data output │ │ • Authentication│ │ • Visualization │
184+
└─────────────────┘ └─────────────────┘ └─────────────────┘
185+
```
186+
187+
The package can work standalone (offline mode) or connect to the API for cloud features and dashboard visualization.
188+
189+
## Tips for Effective Development
190+
191+
1. **Start with tests**: Run existing tests first to understand current state
192+
2. **Use examples**: Check `examples/` directory for usage patterns
193+
3. **Environment isolation**: Use uv for dependency management and virtual environments
194+
4. **Incremental development**: Test frequently with `uv run task test-package`
195+
5. **Check CI**: Ensure your changes pass the same checks as GitHub Actions
196+
6. **Read architecture docs**: Understand the emission calculation methodology in docs/
197+
198+
Remember: CodeCarbon is about measuring computing emissions, in the goal of helping to reduce them. Every contribution helps make computing more sustainable! 🌱

0 commit comments

Comments
 (0)