docs/developer-guide/contributing.md

Conventional Commits Guide

This project uses Conventional Commits 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:

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:

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:

git commit --no-verify -m "emergency fix"

Note: Only use this for genuine emergencies.

References

• Conventional Commits Specification
• Angular Commit Message Guidelines
• Commitizen
• Commitlint