mcp-stream-workflow/.github/COMMIT_CONVENTION.md

Conventional Commit Guidelines

This project uses automated semantic versioning based on commit messages.

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types and Version Bumps

Type	Version Bump	Example
feat:	Minor (0.1.0 → 0.2.0)	New features
fix:	Patch (0.1.0 → 0.1.1)	Bug fixes
feat!: or BREAKING CHANGE:	Major (0.1.0 → 1.0.0)	Breaking changes
chore:, docs:, style:, refactor:, perf:, test:	None (no release)	Non-functional changes

Examples

Minor Version Bump (New Feature)

git commit -m "feat: add getMCPServiceSubdir helper function"
# 1.0.0 → 1.1.0

Patch Version Bump (Bug Fix)

git commit -m "fix: correct version path resolution in ESM modules"
# 1.0.0 → 1.0.1

Major Version Bump (Breaking Change)

git commit -m "feat!: rename createVersionInfo to buildVersionInfo

BREAKING CHANGE: createVersionInfo function renamed to buildVersionInfo.
Update all imports."
# 1.0.0 → 2.0.0

No Version Bump

git commit -m "docs: update installation instructions"
git commit -m "chore: update dependencies"
git commit -m "test: add unit tests for version helper"
# No version bump - no release created

Automation Workflow

On every push to main:

1. GitHub Actions analyzes commits since last tag
2. Determines version bump type
3. Updates package.json
4. Creates git tag
5. Publishes to GitHub Packages
6. Creates GitHub Release

To skip CI (prevent infinite loop):

git commit -m "chore: update docs [skip ci]"

Multi-line Commits

git commit -m "feat: add data directory management

- Add getMCPServiceSubdir() helper
- Support cross-platform cache directories
- Follow OS conventions for temporary data"

Scopes (Optional)

git commit -m "feat(version): add package validation"
git commit -m "fix(types): export MCPResponse interface"
git commit -m "docs(readme): clarify installation steps"

Best Practices

1. One logical change per commit - Makes version history clear
2. Use imperative mood - "add feature" not "added feature"
3. Keep subject line under 72 characters - Better readability
4. Explain WHY in body - What changed is in the diff
5. Reference issues - Fixes #123 in footer

Migration from Manual Versioning

Old workflow (manual):

./release.sh patch
git push origin main --tags

New workflow (automatic):

git commit -m "fix: correct edge case in version detection"
git push origin main
# GitHub Actions handles everything automatically

Troubleshooting

No release created

Cause: Commit type doesn't trigger version bump (e.g., docs:, chore:)

Solution: Use feat: or fix: for releasable changes

Wrong version bump

Cause: Incorrect commit type

Solution: Check commit message follows convention

Release loop

Cause: Missing [skip ci] in automated commits

Solution: Workflow already includes [skip ci] in version bump commits