Git Workflow & Commit Strategy

Last Updated: 2026-02-27

This document outlines the complete git workflow, commit strategy, PR process, and branch management for the Yappa Knowledge Hub project.

Repository Structure

The project uses two separate repositories:

Slack Bot Repository (yappa-knowledge-hub/slack/)
- Node.js/TypeScript codebase
- Slack UI and handlers
- API client services
Symfony Backend Repository (yappa-knowledge-hub/backend/)
- PHP/Symfony codebase
- REST API
- Business logic and AI integration

Commit Strategy

Core Principles

Atomic commits: Each commit represents a complete, logical unit of work
Always link to Jira: Every commit must reference its Jira ticket ID (MSP2-XXX)
Conventional Commits: Follow the specification for consistency
Clear messages: Explain what and why, not how

Commit Message Format

We follow Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Example:

feat(entity): create Role entity

- Add Role entity with name, description, icon fields
- Create migration for role table
- Add RoleRepository with custom queries
- Add fixtures for 8 default roles

Refs: MSP2-461

Commit Types

feat: New feature
fix: Bug fix
refactor: Code refactoring (no functional changes)
perf: Performance improvement
test: Adding or updating tests
docs: Documentation changes
chore: Maintenance tasks (dependencies, config)
style: Code style changes (formatting, no logic changes)
ci: CI/CD changes
build: Build system changes

Commit Scopes

Backend (Symfony):

ai: AI provider integration
summary: Summary generation and management
prompt: Prompt template system
role: Role/target group management
entity: Database entities
api: API endpoints
service: Service layer
migration: Database migrations
test: Test infrastructure

Slack Bot:

ui: User interface components
modal: Modal interactions
handler: Event handlers
service: Service layer
api-client: Backend API client
types: TypeScript types
test: Test infrastructure

Commit Message Best Practices

Keep subject line under 72 characters
Use imperative mood ("Add feature" not "Added feature")
Capitalize first letter of description
No period at end of subject line
Use body to explain "what" and "why", not "how"
Reference Jira ticket in footer with "Refs: MSP2-XXX"
Use "Fixes: #123" for bug fixes

Commit Examples

Backend Repository

Feature Commits

bash

# Entity creation
git commit -m "feat(entity): create Role entity

- Add Role entity with name, description, icon fields
- Create migration for role table
- Add RoleRepository with custom queries
- Add fixtures for 8 default roles

Refs: MSP2-461"

# Service creation
git commit -m "feat(service): implement PromptBuilderService

- Add template rendering with variable substitution
- Implement template inheritance (global → category → custom)
- Add Dutch language directive injection
- Add template validation

Refs: MSP2-460"

# API endpoint
git commit -m "feat(api): add summary generation endpoint

- POST /api/summaries - generate new summary
- Add request validation
- Add response serialization
- Add error handling

Refs: MSP2-459"

Refactor Commits

bash

# Refactoring existing code
git commit -m "refactor(ai): extract OpenAiProvider from OpenAiService

- Create AiProviderInterface
- Implement interface in OpenAiProvider
- Add AiResponse DTO for structured responses
- Update service container configuration

Refs: MSP2-457"

# Removing deprecated code
git commit -m "refactor(service): remove hardcoded TargetGroupService

- Delete TargetGroupService with hardcoded constants
- Update all references to use RoleManagerService
- Remove deprecated methods
- Update tests

Refs: MSP2-XXX"

Fix Commits

bash

# Bug fix
git commit -m "fix(summary): handle null prompt template gracefully

- Add null check before template rendering
- Return default template if custom not found
- Add error logging
- Add test case for null template

Fixes: #123"

Test Commits

bash

# Adding tests
git commit -m "test(summary): add integration tests for AiSummaryService

- Test summary generation flow
- Test regeneration with version increment
- Test edit tracking
- Test error scenarios

Refs: MSP2-455"

Migration Commits

bash

# Database migration
git commit -m "migration: create summary table with relationships

- Add summary table with foreign keys
- Add indexes for performance
- Add version field for history tracking
- Add metadata JSON field

Refs: MSP2-456"

Slack Bot Repository

Feature Commits

bash

# UI feature
git commit -m "feat(modal): implement summary edit modal

- Create edit modal with text area
- Add validation for content length
- Add save handler
- Update summary display with edit badge

Refs: MSP2-481"

# Handler feature
git commit -m "feat(handler): add regenerate summary action

- Add regenerate button to summary blocks
- Create confirmation modal
- Call backend regenerate endpoint
- Update UI on completion

Refs: MSP2-475"

# Service feature
git commit -m "feat(service): enhance aiSummary service with metadata

- Add metadata display (version, model, cost)
- Add history fetching
- Add error handling
- Update types

Refs: MSP2-35"

Fix Commits

bash

# Bug fix
git commit -m "fix(ui): correct target group ID mismatch

- Update hardcoded IDs to match backend
- Fetch roles from API instead of constants
- Update icon and name mapping
- Fix broken summary display

Fixes: #456"

Refactor Commits

bash

# Code cleanup
git commit -m "refactor(service): remove hardcoded target groups

- Delete targetGroups.ts constants
- Fetch roles from backend API
- Update all references
- Add caching for role data

Refs: MSP2-XXX"

Branch Strategy

Branch Naming Convention

<type>/<ticket-id>-<short-description>

Examples:
feature/MSP2-461-create-role-entity
fix/MSP2-481-edit-modal-validation
refactor/MSP2-457-ai-provider-interface
hotfix/fix-summary-generation-error

Branch Types

feature/ - New features
fix/ - Bug fixes
refactor/ - Code refactoring
hotfix/ - Urgent production fixes
chore/ - Maintenance tasks
docs/ - Documentation updates

Workflow

Create Feature Branch

bash

git checkout -b feature/MSP2-461-create-role-entity

Make Commits

bash

# Small, focused commits
git add src/Entity/Role.php
git commit -m "feat(entity): create Role entity"

git add migrations/VersionXXX_CreateRoleTable.php
git commit -m "migration: create role table"

git add src/DataFixtures/RoleFixtures.php
git commit -m "feat(entity): add role fixtures"

git add tests/Unit/Entity/RoleTest.php
git commit -m "test(entity): add Role entity tests"

Push Branch

bash

git push origin feature/MSP2-461-create-role-entity

Create Pull Request
- Use PR template (see below)
- Link to Jira ticket
- Request reviews
Merge to Main
- Squash commits if many small WIP commits
- Keep commits if they tell a story
- Delete branch after merge

Pull Request Strategy

When to Create a PR

Feature is complete and tested
All tests pass
Code is self-reviewed
Documentation is updated
Jira ticket is ready for review

PR Title Format

[MSP2-XXX] Brief description of changes

Examples:
[MSP2-461] Create Role entity for target groups
[MSP2-481] Implement summary edit modal
[MSP2-457, MSP2-460] Refactor AI services and add prompt builder

Backend PR Template

markdown

## Description
Brief description of changes

## Jira Ticket
MSP2-XXX

## Type of Change
- [ ] New feature
- [ ] Bug fix
- [ ] Refactoring
- [ ] Performance improvement
- [ ] Documentation update

## Changes Made
- Bullet list of changes
- Be specific

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed
- [ ] All tests passing

## Database Changes
- [ ] Migration created
- [ ] Migration tested
- [ ] Rollback tested
- [ ] Fixtures updated

## API Changes
- [ ] New endpoints documented
- [ ] Breaking changes documented
- [ ] Backward compatibility maintained

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
- [ ] No new warnings
- [ ] Tests added and passing
- [ ] Dependent changes merged

## Screenshots (if UI changes)
N/A for backend

## Additional Notes
Any additional context

Slack Bot PR Template

markdown

## Description
Brief description of changes

## Jira Ticket
MSP2-XXX

## Type of Change
- [ ] New feature
- [ ] Bug fix
- [ ] Refactoring
- [ ] UI improvement
- [ ] Documentation update

## Changes Made
- Bullet list of changes
- Be specific

## Testing
- [ ] Unit tests added/updated
- [ ] Manual testing in Slack workspace
- [ ] All tests passing
- [ ] Tested on mobile (if applicable)

## UI Changes
- [ ] Screenshots attached
- [ ] Accessibility checked
- [ ] Responsive design verified
- [ ] Loading states implemented
- [ ] Error states implemented

## API Integration
- [ ] Backend endpoints tested
- [ ] Error handling implemented
- [ ] Types updated

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
- [ ] No TypeScript errors
- [ ] Tests added and passing
- [ ] Dependent changes merged

## Screenshots
[Attach screenshots of UI changes]

## Additional Notes
Any additional context

Merge Strategy

Squash Merge (Recommended for Feature Branches)

Combines all commits into one
Clean main branch history
Use when commits are WIP or too granular

Rebase Merge (For Clean Commit History)

Preserves individual commits
Linear history
Use when commits tell a story

Merge Commit (For Long-Running Branches)

Preserves branch history
Shows when feature was merged
Use for release branches

Workflow Scenarios

Scenario 1: Simple Feature (Single Ticket)

bash

# 1. Create branch
git checkout -b feature/MSP2-461-create-role-entity

# 2. Make changes and commit
git add src/Entity/Role.php
git commit -m "feat(entity): create Role entity

Refs: MSP2-461"

# 3. Push and create PR
git push origin feature/MSP2-461-create-role-entity
# Create PR on GitHub/GitLab

# 4. After approval, merge
git checkout main
git merge feature/MSP2-461-create-role-entity
git push origin main
git branch -d feature/MSP2-461-create-role-entity

Scenario 2: Complex Feature (Multiple Commits)

bash

# 1. Create branch
git checkout -b feature/MSP2-461-create-role-entity

# 2. Make multiple focused commits
git add src/Entity/Role.php
git commit -m "feat(entity): create Role entity"

git add migrations/VersionXXX_CreateRoleTable.php
git commit -m "migration: create role table"

git add src/Repository/RoleRepository.php
git commit -m "feat(entity): add RoleRepository"

git add src/DataFixtures/RoleFixtures.php
git commit -m "feat(entity): add role fixtures"

git add tests/Unit/Entity/RoleTest.php
git commit -m "test(entity): add Role entity tests"

# 3. Push and create PR
git push origin feature/MSP2-461-create-role-entity

# 4. Keep commits or squash based on preference

Scenario 3: Hotfix

bash

# 1. Create hotfix branch from main
git checkout main
git pull
git checkout -b hotfix/fix-summary-generation-error

# 2. Fix the issue
git add src/Service/Summary/AiSummaryService.php
git commit -m "fix(summary): handle empty content gracefully

- Add null check before AI generation
- Return error message instead of exception
- Add logging for debugging

Fixes: #789"

# 3. Push and create PR
git push origin hotfix/fix-summary-generation-error

# 4. Merge to main and tag
git checkout main
git merge hotfix/fix-summary-generation-error
git tag -a v1.0.1 -m "Hotfix v1.0.1: Fix summary generation error"
git push origin main --tags

# 5. Merge to develop (if using gitflow)
git checkout develop
git merge hotfix/fix-summary-generation-error
git push origin develop

Commit Frequency

Do:

✅ Commit after completing a logical unit of work
✅ Commit before switching tasks
✅ Commit before refactoring
✅ Commit tests separately from implementation
✅ Commit migrations separately

Don't:

❌ Commit broken code
❌ Commit commented-out code
❌ Commit debug statements
❌ Commit large, unfocused changes
❌ Commit without testing

Code Review Checklist

For Reviewers

[ ] Code follows style guidelines
[ ] Logic is clear and well-commented
[ ] Tests are comprehensive
[ ] No security vulnerabilities
[ ] Performance is acceptable
[ ] Documentation is updated
[ ] Commit messages are clear
[ ] No unnecessary changes

For Authors

[ ] Self-review completed
[ ] All tests passing
[ ] No debug code left
[ ] Documentation updated
[ ] Breaking changes documented
[ ] Migration tested (if applicable)
[ ] Backward compatibility maintained (if applicable)

Release Tagging

bash

# Tag release
git tag -a v1.0.0 -m "Release v1.0.0: AI Summary MVP

Features:
- Role-based summary generation
- Prompt template system
- Summary editing and regeneration
- Slack UI integration

Refs: Sprint 1 completion"

# Push tag
git push origin v1.0.0

Troubleshooting

Problem: Forgot to reference ticket in commit

bash

# Amend last commit
git commit --amend -m "feat(entity): create Role entity

Refs: MSP2-461"

# If already pushed
git push --force-with-lease

Problem: Need to split a large commit

bash

# Reset last commit but keep changes
git reset HEAD~1

# Stage and commit in smaller chunks
git add src/Entity/Role.php
git commit -m "feat(entity): create Role entity"

git add migrations/
git commit -m "migration: create role table"

Problem: Accidentally committed to wrong branch

bash

# Create new branch from current state
git branch feature/MSP2-461-create-role-entity

# Reset current branch
git reset --hard origin/main

# Switch to new branch
git checkout feature/MSP2-461-create-role-entity

Problem: Need to update PR after review

bash

# Make changes
git add .
git commit -m "fix(entity): address review comments"

# Push to same branch
git push origin feature/MSP2-461-create-role-entity
# PR automatically updates

Git Aliases (Optional)

Add to ~/.gitconfig:

ini

[alias]
    # Quick status
    st = status -sb

    # Pretty log
    lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

    # Amend last commit
    amend = commit --amend --no-edit

    # Undo last commit but keep changes
    undo = reset HEAD~1

    # List branches sorted by last modified
    branches = branch --sort=-committerdate

Best Practices Summary

Always link commits to Jira tickets
Write clear, descriptive commit messages
Make atomic commits (one logical change per commit)
Test before committing
Review your own code before creating PR
Keep PRs focused and reasonably sized
Respond to review comments promptly
Delete branches after merging
Keep main branch stable (all tests pass)
Use conventional commits for consistency

Maintained by: Development Team Last Updated: 2026-02-27 Version: 2.0 (Merged from git-workflow.md and git-commit-strategy.md)

Git Workflow & Commit Strategy ​

Repository Structure ​

Commit Strategy ​

Core Principles ​

Commit Message Format ​

Commit Types ​

Commit Scopes ​

Commit Message Best Practices ​

Commit Examples ​

Backend Repository ​

Feature Commits ​

Refactor Commits ​

Fix Commits ​

Test Commits ​

Migration Commits ​

Slack Bot Repository ​

Feature Commits ​

Fix Commits ​

Refactor Commits ​

Branch Strategy ​

Branch Naming Convention ​

Branch Types ​

Workflow ​

Pull Request Strategy ​

When to Create a PR ​

PR Title Format ​

Backend PR Template ​

Slack Bot PR Template ​

Merge Strategy ​

Squash Merge (Recommended for Feature Branches) ​

Rebase Merge (For Clean Commit History) ​

Merge Commit (For Long-Running Branches) ​

Workflow Scenarios ​

Scenario 1: Simple Feature (Single Ticket) ​

Scenario 2: Complex Feature (Multiple Commits) ​

Scenario 3: Hotfix ​

Commit Frequency ​

Do: ​

Don't: ​

Code Review Checklist ​

For Reviewers ​

For Authors ​

Release Tagging ​

Troubleshooting ​

Problem: Forgot to reference ticket in commit ​

Problem: Need to split a large commit ​

Problem: Accidentally committed to wrong branch ​

Problem: Need to update PR after review ​

Git Aliases (Optional) ​

Best Practices Summary ​

Git Workflow & Commit Strategy

Repository Structure

Commit Strategy

Core Principles

Commit Message Format

Commit Types

Commit Scopes

Commit Message Best Practices

Commit Examples

Backend Repository

Feature Commits

Refactor Commits

Fix Commits

Test Commits

Migration Commits

Slack Bot Repository

Feature Commits

Fix Commits

Refactor Commits

Branch Strategy

Branch Naming Convention

Branch Types

Workflow

Pull Request Strategy

When to Create a PR

PR Title Format

Backend PR Template

Slack Bot PR Template

Merge Strategy

Squash Merge (Recommended for Feature Branches)

Rebase Merge (For Clean Commit History)

Merge Commit (For Long-Running Branches)

Workflow Scenarios

Scenario 1: Simple Feature (Single Ticket)

Scenario 2: Complex Feature (Multiple Commits)

Scenario 3: Hotfix

Commit Frequency

Do:

Don't:

Code Review Checklist

For Reviewers

For Authors

Release Tagging

Troubleshooting

Problem: Forgot to reference ticket in commit

Problem: Need to split a large commit

Problem: Accidentally committed to wrong branch

Problem: Need to update PR after review

Git Aliases (Optional)

Best Practices Summary