docs/developer-guide/contributing.md

# Conventional Commits Guide

This project uses [Conventional Commits](https://www.conventionalcommits.org/) to ensure consistent, readable commit messages that can be automatically processed for changelog generation and semantic versioning.

## Quick Start

### Using Commitizen (Recommended)
Instead of `git commit`, use:
```bash
npm run commit
# or directly
npx cz
```
This will prompt you through creating a properly formatted commit message.

### Manual Format
If writing commit messages manually, follow this structure:
```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

## Commit Types

| Type | Description | SemVer Impact |
|------|-------------|---------------|
| `feat` | New feature | MINOR |
| `fix` | Bug fix | PATCH |
| `docs` | Documentation only | - |
| `style` | Formatting, missing semi-colons, etc. | - |
| `refactor` | Code change that neither fixes a bug nor adds a feature | - |
| `perf` | Performance improvement | PATCH |
| `test` | Adding tests | - |
| `build` | Build system changes | - |
| `ci` | CI configuration changes | - |
| `chore` | Other changes that don't modify src or test files | - |
| `revert` | Revert a previous commit | - |

## Scopes

Use these scopes to indicate which part of the codebase is affected:

### Core Modules
- `kg` - Knowledge graph related (InMemoryKG, etc.)
- `embedder` - Embedding service functionality
- `ontology` - Data models and ontology (MCPTool, etc.)
- `agent` - Agent-related functionality
- `planner` - Planning and orchestration
- `ui` - User interface components
- `api` - API endpoints

### Infrastructure
- `deps` - Dependencies updates
- `config` - Configuration changes
- `scripts` - Scripts and automation
- `ci` - CI/CD pipeline
- `docs` - Documentation
- `tests` - Testing infrastructure

## Examples

### Good Commit Messages

#### Features
```
feat(kg): implement cosine similarity search in InMemoryKG

- Add _cosine_similarity method using numpy
- Implement find_similar_tools with top_k parameter
- Handle edge cases for empty vectors and indexes
```

```
feat(embedder): add live OpenAI API integration

Integrate OpenAI text-embedding-3-small model for real embeddings
replacing the placeholder hash-based implementation.
```

#### Bug Fixes
```
fix(kg): handle zero vectors in cosine similarity calculation

Previously returned NaN when calculating similarity with zero vectors.
Now returns 0.0 as expected.
```

#### Documentation
```
docs(api): add embedder service API documentation

Document all public methods including get_embedding and error handling.
```

#### Chores
```
chore(deps): update numpy to 1.26.0

Update numpy dependency for improved performance and security fixes.
```

#### Tests
```
test(kg): add integration tests for semantic search pipeline

Add comprehensive tests covering embeddings → indexing → search workflow
with mocked OpenAI API calls.
```

### Breaking Changes

When introducing breaking changes, add `!` after the type/scope:
```
feat(api)!: change embedder interface to async

BREAKING CHANGE: EmbeddingService.get_embedding() now returns a coroutine.
All callers must be updated to use await.
```

## Validation

Commit messages are automatically validated using commitlint when you commit. If a message doesn't follow the convention, the commit will be rejected with helpful error messages.

To manually validate a commit message:
```bash
echo "feat(kg): add new feature" | npx commitlint
```

## Integration with Development Workflow

### Sprint Tasks
When working on sprint tasks, include the task information in the commit body:
```
feat(kg): implement vector index building

Complete Task 2.2 from Sprint 2: Real Embeddings & Semantic Search Logic.
Add build_vector_index method that integrates with EmbeddingService
to create real vector representations of tools.

Closes: #9
```

### Pull Requests
PR titles should follow the same conventional format as commit messages. The PR description should reference related tasks and provide context.

## Benefits

1. **Automated Changelog**: Tools can generate changelogs from commit history
2. **Semantic Versioning**: Commit types map to version bumps (feat → minor, fix → patch)
3. **Better Code Review**: Clear indication of change type and scope
4. **Improved Git History**: Consistent, searchable commit messages
5. **Tool Integration**: Many tools understand conventional commits for automation

## Troubleshooting

### Commitlint Errors
If commitlint rejects your commit:
1. Check the error message for specific issues
2. Ensure you're using a valid type and scope
3. Keep the subject line under 72 characters
4. Use present tense ("add" not "added")

### Bypassing Validation (Emergency Only)
In rare cases where you need to bypass validation:
```bash
git commit --no-verify -m "emergency fix"
```
**Note**: Only use this for genuine emergencies.

## References

- [Conventional Commits Specification](https://www.conventionalcommits.org/)
- [Angular Commit Message Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)
- [Commitizen](https://github.com/commitizen/cz-cli)
- [Commitlint](https://commitlint.js.org/)