Mantle

Appearance

Git Workflow ​

Quick Reference ​

  • When to use: Every git commit, push, and pull request
  • Enforcement: Required - consistent Git practices
  • Impact if violated: High - messy history, broken CI

The Rule ​

Follow conventional commits, use feature branches, and verify before pushing.

Required Workflow ​

  1. Create a feature branch from main
  2. Make code changes
  3. Run verification: pnpm run format && pnpm turbo build && pnpm test
  4. Stage and commit with a conventional commit message
  5. Push and create a pull request
  6. Merge to main after review

Commit Message Standards ​

Follow Conventional Commits:

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

Types ​

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • style: Code style (formatting)
  • refactor: Code restructuring
  • test: Adding/updating tests
  • chore: Maintenance tasks

Examples ​

Correct ​

bash
git commit -m "feat: add S3 upload retry mechanism"
git commit -m "fix(core): resolve middleware chain execution order"
git commit -m "refactor(database): extract query metrics to shared utility"
git commit -m "docs: update entity query guide"
git commit -m "test(aws): add integration tests for DynamoDB operations"
git commit -m "chore: update dependencies"

Incorrect ​

bash
# Too vague
git commit -m "update"
git commit -m "changes"
git commit -m "fix stuff"

# Not conventional commits format
git commit -m "Added the new feature for users"
git commit -m "Fixed bug"

Pre-Commit Verification ​

Required Checks ​

bash
# 1. Format code
pnpm run format

# 2. Lint code
pnpm run lint

# 3. Build all packages
pnpm turbo build

# 4. Run tests
pnpm test

Branch Management ​

Branch Naming ​

Use descriptive, lowercase, hyphen-separated names with a type prefix:

bash
# Good branch names
feat/user-authentication
fix/memory-leak-webhook
refactor/database-queries
chore/update-dependencies
docs/entity-query-guide

# Poor branch names
feature_user_auth   # Use hyphens, not underscores
FixMemoryLeak       # Use lowercase
new-stuff           # Be specific

Working with Worktrees ​

For parallel feature development, use git worktrees:

bash
# Create worktree with feature branch
git worktree add -b feat/my-feature ~/wt/my-feature main

# Work in the worktree
cd ~/wt/my-feature
pnpm install

# After merge, cleanup
cd /path/to/mantle
git worktree remove ~/wt/my-feature
git branch -d feat/my-feature

Worktree Benefits ​

  • Isolation - Changes don't affect main until merged
  • Multiple features - Work on several features simultaneously
  • Safe experimentation - Easy to discard failed attempts

Pull Request Guidelines ​

PR Title ​

Same as commit message format:

  • Follow conventional commits
  • Keep concise and descriptive

PR Description Template ​

markdown
## Summary
Brief description of changes

## Changes Made
- Specific change 1
- Specific change 2

## Testing
- [ ] Unit tests pass (`pnpm test`)
- [ ] Build succeeds (`pnpm turbo build`)
- [ ] Lint passes (`pnpm run lint`)
- [ ] Format checked (`pnpm run format:check`)

## Checklist
- [ ] Code follows project conventions
- [ ] Documentation updated if needed
- [ ] Tests added/updated

Monorepo Considerations ​

Turborepo Integration ​

Turborepo caches build outputs. After making changes:

bash
# Build only affected packages (Turborepo handles dependency graph)
pnpm turbo build

# Build a specific package
pnpm turbo build --filter=@mantleframework/core

# Run tests for specific package
pnpm turbo test --filter=@mantleframework/aws

Changesets ​

For versioning and changelogs:

bash
# Create a changeset describing your changes
pnpm changeset

# Follow prompts to select packages and bump type

Enforcement ​

Automated ​

  • CI Pipeline - Build, lint, test on every PR
  • Turborepo - Ensures dependency graph is respected

Code Review Checklist ​

  • [ ] Conventional commit format used
  • [ ] Clean, professional messages
  • [ ] All tests pass
  • [ ] Code formatted with dprint
  • [ ] Code linted with ESLint
  • [ ] Feature branch (not direct to main)

Consistent Git practices keep the repository clean and maintainable. Follow conventional commits and always verify before pushing.