Contributing¶

This guide covers how to contribute to Carbon Connect, including branch conventions, PR workflows, and the TDD gate.

Getting Started¶

1. Clone the repository
2. Follow the Local Development Setup instructions
3. Create a feature branch from main
4. Write tests, implement changes, verify locally
5. Open a PR following the template

Branch Naming¶

Branches follow a type-based naming convention:

Commit Conventions¶

Commits follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types¶

Examples¶

feat(matching): add carbon certification scoring component

fix(auth): resolve JWT refresh token race condition

test(pipeline): add IATI client integration tests

chore(deps): update anthropic SDK to 0.40.0

Pull Request Process¶

PR Template¶

Every PR must include these sections:

## Summary
Brief description of what this PR does.

## TDD Proof
- [x] Tests written before production code
- [x] Evidence of failing test run included
- [x] All tests passing locally
- [x] Docs/configs updated
- [x] No secrets introduced

## Test Evidence
<!-- Paste screenshots or terminal output showing:
1. Tests failing BEFORE implementation
2. Tests passing AFTER implementation -->

## Changes
- List of specific changes made

TDD Gate¶

The PR TDD Gate workflow (pr-tdd-gate.yml) automatically checks every PR for:

1. Presence of a ## TDD Proof section in the PR body
2. All checklist items are checked ([x])
3. Specifically validates:
   • "Tests written before production code"
   • "Evidence of failing test run included"
   • "All tests passing locally"

Quality Gates¶

Before a PR can be merged, these automated checks must pass:

Code Review¶

Review Expectations¶

• All PRs require at least one approval
• Reviewers should verify TDD evidence
• Focus on:
  • Correctness of business logic
  • Error handling completeness
  • Test quality and coverage
  • Performance implications
  • Security considerations

Auto-Labeling¶

PRs are automatically labeled based on:

• File paths -- backend, frontend, infra, docs
• Size -- XS (<10 lines), S (<50), M (<200), L (<500), XL (>500)

XL pull requests receive a warning to consider breaking into smaller PRs.

Pre-commit Hooks¶

Install pre-commit hooks after cloning:

poetry run pre-commit install

Hooks run automatically on every commit:

Manual Run¶

# Run on all files
poetry run pre-commit run --all-files

# Update secrets baseline (when intentional secrets change)
poetry run detect-secrets scan > .secrets.baseline

Release Process¶

1. Create a release branch or tag following semver: v1.2.3
2. The Release workflow generates a changelog from merged PRs
3. A GitHub Release is created with categorized changes
4. Production deployment is triggered (with manual approval)

Dependency Management¶

Python (Backend)¶

# Add dependency
poetry add <package>

# Add dev dependency
poetry add --group dev <package>

# Update dependencies
poetry update

Node.js (Frontend)¶

cd frontend
npm install <package>
npm install --save-dev <package>

Automated Updates¶

Dependabot is configured for:

• Weekly pip dependency updates
• Weekly npm dependency updates
• Automatic PR creation for security patches