Commit Messages

Wellpipe uses Conventional Commits for clear, structured commit history.

Format

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

[optional body]

[optional footer]

Types

Type	Description	Example
feat	New feature	feat: add sleep trend analysis tool
fix	Bug fix	fix: handle expired refresh tokens
docs	Documentation	docs: update API reference
refactor	Code change that neither fixes a bug nor adds a feature	refactor: extract token refresh logic
test	Adding or updating tests	test: add coverage for rate limiting
chore	Build process or auxiliary tool changes	chore: update dependencies
style	Code style (formatting, semicolons, etc.)	style: fix indentation in client.ts
perf	Performance improvement	perf: cache token validation result

Scope (Optional)

The scope provides additional context:

• feat(sleep): add sleep stage breakdown
• fix(oauth): handle token refresh race condition
• docs(api): add examples for recovery tools

Common scopes:

• sleep, recovery, workout, cycle - Data domains
• oauth, auth - Authentication
• api, mcp - Integration layers
• cli, cloud - Deployment targets

Examples

Simple Commit

feat: add sleep summary tool

With Scope

fix(oauth): handle token refresh race condition

With Body

feat: add recovery trend analysis

Adds a new tool that analyzes recovery trends over time
and identifies patterns related to sleep and strain.

Includes:
- 7-day rolling average calculation
- Correlation with sleep metrics
- Warning for declining trends

With Breaking Change

feat!: change TokenProvider interface

BREAKING CHANGE: TokenProvider.getToken() is now async and returns Promise<string>.
Previously it returned string synchronously.

Migration:
- Change `provider.getToken()` to `await provider.getToken()`
- Ensure calling code is async

With Issue Reference

fix: resolve rate limit bypass

Fixes #123

Writing Good Descriptions

Do

• Use imperative mood: "add feature" not "added feature"
• Keep under 50 characters
• Capitalize first letter
• No period at the end

Don't

• ❌ Added the new feature for users
• ❌ feat: add feature.
• ❌ FEAT: ADD FEATURE

Good Examples

feat: add sleep efficiency calculation
fix: prevent duplicate token refresh requests
docs: clarify OAuth setup steps
refactor: simplify date range validation
test: add edge cases for empty responses

Bad Examples

❌ updated stuff
❌ fix bug
❌ WIP
❌ feat: Added new feature for calculating sleep efficiency scores for users.

Body Guidelines

• Wrap at 72 characters
• Explain what and why, not how
• Use bullet points for multiple changes
• Reference issues when relevant

Footer Guidelines

Breaking Changes

BREAKING CHANGE: description of what broke and how to migrate

Issue References

Fixes #123
Closes #456
Relates to #789

Automation

Commit messages may trigger:

• Changelog generation
• Version bumping
• Release notes

feat → minor version bump fix → patch version bump feat! or BREAKING CHANGE → major version bump

Squashing

When your PR is merged, commits may be squashed. Ensure your PR title follows these conventions—it becomes the squashed commit message.