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

Manual Format¶

If writing commit messages manually, follow this structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types¶

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"

References¶

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