Skip to main content
GAIA follows the Conventional Commits specification for commit messages and PR titles.

​
Format

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

[optional body]

[optional footer(s)]

​
Type

The commit type must be one of the following:
A new feature for the user or a particular part of the application.
feat(agents): add weather forecast tool
feat(api): implement calendar event sync
feat(web): add dark mode toggle
A bug fix that resolves an issue.
fix(api): resolve todo creation race condition
fix(web): correct timezone display in calendar
fix(agents): handle empty response from LLM
Documentation only changes.
docs: update agent development guide
docs(api): add authentication examples
docs: fix typo in contributing guide
Changes that don’t affect code meaning (formatting, missing semicolons, etc.).
style: fix linting issues in todo tool
style(web): format with Biome
style: remove trailing whitespace
Code change that neither fixes a bug nor adds a feature.
refactor(agents): simplify tool registry logic
refactor(api): extract user service functions
refactor: consolidate error handling
Adding missing tests or correcting existing tests.
test(agents): add integration tests for comms agent
test: improve todo tool test coverage
test(api): add edge case tests for calendar sync
Changes to build process, dependencies, or auxiliary tools.
chore: update dependencies
chore(api): bump fastapi to 0.115.6
chore: clean up unused imports
Changes to CI/CD configuration files and scripts.
ci: add code coverage reporting
ci: update GitHub Actions workflow
ci: configure pre-commit hooks
Changes affecting build system or external dependencies.
build: update Nx to version 20
build(api): configure Docker multi-stage build
build: optimize production bundle size
Code changes that improve performance.
perf(api): optimize database queries
perf(agents): reduce memory usage in tool registry
perf(web): lazy load todo list components
Reverts a previous commit.
revert: feat(agents): add weather forecast tool

This reverts commit abc123.
Additional types used in GAIA:
  • deps - Dependency updates
  • infra - Infrastructure changes
  • security - Security fixes
  • env - Environment configuration
  • i18n - Internationalization
  • ux - User experience improvements
  • config - Configuration changes
  • assets - Asset updates
  • meta - Meta changes
  • release - Release commits

​
Scope

The scope is optional but recommended. It provides context about what part of the codebase is affected. Common scopes:
  • agents - Agent system
  • tools - Agent tools
  • api - Backend API
  • web - Web application
  • desktop - Desktop application
  • mobile - Mobile application
  • db - Database
  • auth - Authentication
  • integrations - Third-party integrations

​
Description

The description is a short summary of the change:
  • Use imperative, present tense: “add” not “added” nor “adds”
  • Don’t capitalize first letter
  • No period (.) at the end
  • Keep it concise (under 72 characters)
Good examples: 
add weather forecast tool
fix todo creation race condition
update agent development guide
Bad examples: 
Added weather forecast tool.  # Capitalized and has period
Fixed a bug                   # Not specific enough
Updates                       # Too vague

​
Body

The body is optional but recommended for complex changes:
  • Explain what and why, not how
  • Use bullet points for multiple changes
  • Wrap at 72 characters
  • Separate from description with blank line
Example: 
feat(agents): add weather forecast tool

Add 5-day weather forecast capability:
- Extended API integration
- Added forecast data structures  
- Updated tool documentation

This enables users to plan activities based on upcoming weather.
The footer is optional and used for:

​
Breaking Changes

feat(api)!: change authentication flow

BREAKING CHANGE: Auth tokens now expire after 1 hour instead of 24 hours.
Update client applications to refresh tokens more frequently.

​
Issue References

fix(api): resolve todo creation race condition

Closes #123
References #456, #789

​
Co-authors

feat(agents): add weather forecast tool

Co-authored-by: Alice <[email protected]>
Co-authored-by: Bob <[email protected]>

​
Examples

​
Simple Commit

git commit -m "fix(api): resolve todo creation race condition"

​
Commit with Body

git commit -m "feat(agents): add weather forecast tool

Add 5-day weather forecast capability:
- Extended API integration
- Added forecast data structures
- Updated tool documentation

Closes #234"

​
Breaking Change

git commit -m "feat(api)!: change authentication flow

BREAKING CHANGE: Auth tokens now expire after 1 hour.
Update client applications to refresh tokens frequently.

Closes #345"

​
Multiple Changes

git commit -m "refactor(agents): improve tool registry

- Simplify tool registration logic
- Add lazy loading for dynamic tools
- Improve error handling
- Update tests and documentation

This refactoring reduces memory usage by 30% and improves
startup time by deferring tool initialization."

​
Real Examples from GAIA

​
Feature Addition

feat(agents): add memory search tool

Implement semantic search across conversation history:
- Add search_memory tool with embedding support
- Integrate with ChromaDB for vector search
- Add rate limiting and caching
- Include comprehensive tests

Enables agents to reference past conversations for context.

Closes #456

​
Bug Fix

fix(api): prevent duplicate todo creation

Add transaction locking to prevent race conditions when
creating todos from parallel requests.

Fixes #123

​
Performance Improvement

perf(agents): optimize tool retrieval

Implement caching layer for tool registry:
- Cache tool definitions in Redis
- Add cache invalidation on updates
- Reduce database queries by 80%

Improves agent response time by 200ms on average.

​
Documentation

docs: add agent development guide

Create comprehensive guide covering:
- Agent architecture and patterns
- Tool creation with examples
- Prompt engineering best practices
- Testing strategies

​
Commit Message Tips

1

Write Clear Descriptions

Make the one-line description informative enough to understand the change without reading the body.
2

Explain Why, Not How

The diff shows how you changed the code. The commit message should explain why.
3

Use Present Tense

Write as if giving commands: “add feature” not “added feature”.
4

Reference Issues

Always reference related issues using Closes #123 or References #456.
5

Break Down Large Changes

Multiple logical changes should be separate commits, not one large commit.
Common Mistakes to Avoid:
  • Vague descriptions (“fix bug”, “update code”)
  • Missing type or scope
  • Capitalizing description
  • Period at end of description
  • Mixing multiple unrelated changes
  • Not referencing issues

​
Commit Message Template

Create a git commit template: 
# ~/.gitmessage
type(scope): description

# Body: Explain what and why (not how)
# - Bullet points are fine
# - Wrap at 72 characters

# Footer: Reference issues and breaking changes
# Closes #123
# BREAKING CHANGE: description

# Types: feat, fix, docs, style, refactor, test, chore, ci, build, perf, revert
# Scopes: agents, tools, api, web, desktop, mobile, db, auth, integrations
Configure git to use it: 
git config --global commit.template ~/.gitmessage

​
Validation

GAIA validates commit messages and PR titles automatically:

​
PR Title Validation

GitHub Actions validates PR titles (.github/workflows/pr-naming-conventions.yml): 
- name: Validate PR title
  uses: amannn/[email protected]
  with:
    types: |
      feat
      fix
      docs
      style
      refactor
      test
      chore
      ci
      build
      revert
      perf
      release
      deps
      infra
      security

​
Pre-commit Hooks

Optionally add commitlint to pre-commit hooks: 
# .pre-commit-config.yaml
- repo: https://github.com/commitizen-tools/commitizen
  rev: v3.28.0
  hooks:
    - id: commitizen
      stages: [commit-msg]

​
Tools

​
Commitizen

Interactive commit message builder: 
# Install
pip install commitizen

# Use interactive prompt
cz commit

# Or use CLI
cz commit --fix --scope api --message "resolve todo race condition"

​
Git Commit Editor

Use your editor for multi-line commits: 
# Configure editor
git config --global core.editor "vim"

# Commit without -m flag
git add .
git commit
# Editor opens for message

​
Benefits

Following conventional commits provides:

Automated Changelogs

Generate changelogs automatically from commit history.

Semantic Versioning

Determine version bumps based on commit types.

Better Git History

Easy to understand project history at a glance.

Automated Releases

Trigger releases automatically based on commits.

​
Resources

​
Next Steps

Contributing

Full contribution workflow

Pull Requests

PR requirements and process

Code Style

Code formatting guidelines

Build docs developers (and LLMs) love

Get started for freeTalk to us