Pull Request Workflow

This guide covers the full contribution workflow from branch creation to merge.

Branch Naming

Use the following prefixes:

Prefix	Use Case	Example
feat/	New feature	feat/matrix-channel
fix/	Bug fix	fix/session-timeout-panic
refactor/	Code restructuring	refactor/agent-pipeline-split
docs/	Documentation	docs/provider-guide
test/	Test additions	test/cron-executor-coverage
chore/	Tooling, CI, deps	chore/update-tokio-1.35

git checkout -b feat/my-feature main

Commit Messages

Follow Conventional Commits:

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

[optional body]

[optional footer(s)]

Examples

feat(channels): add Microsoft Teams integration

Implements the Channel trait for MS Teams using the Graph API.
Includes webhook-based receive and thread support (Layer 1).

Closes #142

fix(gateway): prevent panic on empty session ID

The session lookup now returns a 400 Bad Request instead of
unwrapping an empty string.

test(agents): add pipeline context assembly tests

Covers edge cases for token budget calculation when system
prompt exceeds the model's context window.

Types

Type	Description
feat	New feature
fix	Bug fix
refactor	Code change that doesn't fix a bug or add a feature
test	Adding or updating tests
docs	Documentation only
perf	Performance improvement
chore	Build, CI, dependency updates
ci	CI/CD changes

Scopes

Use the crate name without the clawdesk- prefix: agents, gateway, domain, channel, providers, storage, cli, tauri, etc.

Creating a Pull Request

1. Push Your Branch

git push origin feat/my-feature

2. PR Title

Use the same Conventional Commit format:

feat(channels): add Microsoft Teams integration

3. PR Description Template

## Summary

Brief description of what this PR does.

## Changes

- Added `TeamsChannel` implementing `Channel` + `Threaded` traits
- Added `TeamsConfig` with serde support
- Registered in `ChannelRegistry`
- Added 12 unit tests and 3 integration tests

## Testing

Describe how you tested the changes:

- [ ] `cargo test --workspace` passes (610+ tests)
- [ ] `cargo clippy --workspace` clean
- [ ] `cargo fmt --check` passes
- [ ] Manual testing with [describe scenario]

## Related Issues

Closes #142

CI Checks

Every PR triggers the following CI pipeline:

┌─────────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ cargo fmt   │────▶│ clippy   │────▶│ test     │────▶│ build    │
│ --check     │     │ -D warns │     │ 610+     │     │ release  │
└─────────────┘     └──────────┘     └──────────┘     └──────────┘

Check	Command	Must Pass
Format	cargo fmt --check	Yes
Lint	cargo clippy --workspace -- -D warnings	Yes
Tests	cargo test --workspace	Yes
Build	cargo build --release	Yes

warning

All four CI checks must pass before a PR can be merged. Fix any failures locally before pushing.

Code Review Process

Reviewer Checklist

• Code follows coding standards
• Error handling uses thiserror (not unwrap/expect)
• Tests cover the new/changed behavior
• Public APIs have doc comments
• No unintended dependency direction violations (hexagonal architecture)
• TOML config additions are documented

Review Labels

Label	Meaning
needs-review	Ready for review
changes-requested	Reviewer requested changes
approved	Ready to merge
blocked	Waiting on external dependency

Merge Strategy

• Squash merge for single-feature PRs
• Merge commit for large multi-commit PRs where history matters
• Delete the branch after merge

After Merge

1. Delete your feature branch
2. Pull latest main
3. Verify CI pipeline on main is green

git checkout main
git pull origin main
git branch -d feat/my-feature

Quick Reference

# Full pre-push check
cargo fmt && cargo clippy --workspace -- -D warnings && cargo test --workspace

tip

Run the full check above before pushing to avoid CI failures. You can add it as a Git pre-push hook.