Instruction file imported from abuabdirohman4/better-planner (.cursor/rules/git-workflow.mdc). Copyright stays with the author.

Git Workflow & Versioning

Overview

Better Planner follows a structured Git workflow that integrates with semantic versioning, automated releases, and professional development practices.

Branch Strategy

Main Branches

• main: Production-ready code, always deployable
• develop: Integration branch for features (optional)
• release/: Release preparation branches
• hotfix/: Critical bug fixes

Feature Branches

• feature/: New features and enhancements
• bugfix/: Bug fixes and patches
• chore/: Maintenance and refactoring
• docs/: Documentation updates

Branch Naming Convention

# Feature branches
feature/project-planning-dashboard
feature/task-management-system
feature/quarter-planning-view
feature/drag-drop-functionality
feature/analytics-dashboard

# Bug fix branches
bugfix/project-creation-issue
bugfix/task-status-sync-fix
bugfix/quarter-selector-bug
bugfix/supabase-auth-problem

# Chore branches
chore/update-dependencies
chore/refactor-project-validation
chore/improve-performance
chore/update-supabase-integration

# Documentation branches
docs/update-api-documentation
docs/add-user-guide
docs/update-changelog

Commit Message Standards

Conventional Commits Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• perf: Performance improvements
• test: Test additions/changes
• chore: Build process, versioning, etc.
• ci: CI/CD changes
• build: Build system changes

Better Planner Specific Examples

Feature Commits

feat: add project planning dashboard with drag-drop
feat(tasks): implement comprehensive task management system
feat(quarter): add quarterly planning and goal setting
feat(analytics): create project progress visualization
feat(auth): implement Supabase authentication integration

Bug Fix Commits

fix: resolve project creation not saving to database
fix(supabase): correct task status sync problems
fix(quarter): fix quarter selector not updating properly
fix(mobile): resolve navigation bar overlapping content
fix(progress): correct project completion calculation logic

Documentation Commits

docs: update API documentation for project endpoints
docs(changelog): add v2.0.0 release notes
docs(readme): update installation instructions
docs(api): document Supabase integration
docs(guide): add user guide for project creation

Refactoring Commits

refactor: improve project validation logic
refactor(components): extract reusable project card component
refactor(api): optimize Supabase API calls
refactor(ui): improve mobile responsiveness
refactor(types): enhance TypeScript type definitions

Performance Commits

perf: optimize project data loading with SWR caching
perf(dashboard): improve dashboard rendering performance
perf(supabase): reduce bundle size for faster loading
perf(api): implement request batching for Supabase
perf(ui): optimize component re-rendering

Chore Commits

chore: update dependencies to latest versions
chore(versioning): bump version to 2.0.0
chore(ci): update GitHub Actions workflow
chore(build): optimize Next.js configuration
chore(scripts): add automated release script

Git Workflow Process

1. Feature Development

# Create feature branch
git checkout -b feature/project-planning-dashboard

# Make changes and commit
git add .
git commit -m "feat: add project planning dashboard with drag-drop functionality"

# Push branch
git push origin feature/project-planning-dashboard

# Create pull request
# Merge after review

2. Bug Fix Process

# Create bugfix branch
git checkout -b bugfix/project-creation-issue

# Fix the bug
git add .
git commit -m "fix: resolve project creation not saving to database"

# Push branch
git push origin bugfix/project-creation-issue

# Create pull request
# Merge after review

3. Release Process

# Ensure main branch is up to date
git checkout main
git pull origin main

# Create release branch
git checkout -b release/2.0.0

# Update changelog and version
# Run version script
./scripts/version.sh minor

# Push release branch
git push origin release/2.0.0

# Create pull request to main
# Merge after review

4. Hotfix Process

# Create hotfix branch from main
git checkout main
git checkout -b hotfix/critical-bug-fix

# Fix the critical bug
git add .
git commit -m "fix: resolve critical authentication issue"

# Push hotfix branch
git push origin hotfix/critical-bug-fix

# Create pull request
# Merge after review

Tag Management

Tag Creation

# Create annotated tag
git tag -a v2.0.0 -m "Release version 2.0.0"

# Create lightweight tag
git tag v2.0.0

# Push tags to remote
git push origin v2.0.0

# Push all tags
git push origin --tags

Tag Management

# List all tags
git tag -l

# List tags with pattern
git tag -l "v2.*"

# Show tag details
git show v2.0.0

# Delete local tag
git tag -d v2.0.0

# Delete remote tag
git push origin :refs/tags/v2.0.0

Versioning Integration

Pre-Release Checklist

• All changes committed
• No uncommitted changes
• All tests passing
• Code reviewed
• Changelog updated
• Version ready to bump

Release Process

# 1. Update changelog
# Edit CHANGELOG.md with new changes

# 2. Run version script
./scripts/version.sh minor

# 3. Review changes
git diff

# 4. Push to remote
git push origin main
git push origin v2.0.0

# 5. Create GitHub release
# Go to GitHub and create release

Post-Release Process

• Verify release on GitHub
• Check deployment
• Monitor for issues
• Update documentation
• Notify team

Git Hooks Integration

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit

# Run linting
npm run lint

# Run type checking
npm run type-check

# Run tests
npm test

Commit-msg Hook

#!/bin/sh
# .git/hooks/commit-msg

# Validate commit message format
commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|ci|build)(\(.+\))?: .{1,50}'

if ! grep -qE "$commit_regex" "$1"; then
    echo "Invalid commit message format!"
    echo "Format: type(scope): description"
    exit 1
fi

Conflict Resolution

Merge Conflicts

# Check for conflicts
git status

# Resolve conflicts in files
# Edit conflicted files

# Add resolved files
git add .

# Complete merge
git commit

Rebase Conflicts

# Start interactive rebase
git rebase -i HEAD~3

# Resolve conflicts
# Edit conflicted files

# Add resolved files
git add .

# Continue rebase
git rebase --continue

Best Practices

Git Best Practices

• ✅ Use descriptive commit messages
• ✅ Make small, focused commits
• ✅ Use conventional commit format
• ✅ Keep main branch clean
• ✅ Use feature branches
• ✅ Review code before merging
• ✅ Use meaningful branch names
• ✅ Tag releases properly

Versioning Best Practices

• ✅ Follow semantic versioning
• ✅ Update changelog for every release
• ✅ Test before releasing
• ✅ Use automated scripts
• ✅ Keep version history
• ✅ Document breaking changes
• ✅ Plan release schedule
• ✅ Monitor post-release

Workflow Best Practices

• ✅ Use pull requests for code review
• ✅ Keep branches up to date
• ✅ Resolve conflicts quickly
• ✅ Use meaningful PR titles
• ✅ Include detailed PR descriptions
• ✅ Test before merging
• ✅ Clean up merged branches
• ✅ Document workflow changes

Troubleshooting

Common Issues

Uncommitted Changes

# Check status
git status

# Stash changes
git stash

# Apply stashed changes
git stash pop

# List stashes
git stash list

Merge Conflicts

# Abort merge
git merge --abort

# Abort rebase
git rebase --abort

# Reset to previous state
git reset --hard HEAD~1

Tag Issues

# Delete local tag
git tag -d v1.1.0

# Delete remote tag
git push origin :refs/tags/v1.1.0

# Recreate tag
git tag -a v1.1.0 -m "Release version 1.1.0"

Branch Issues

# Delete local branch
git branch -d feature-branch

# Delete remote branch
git push origin --delete feature-branch

# Force delete local branch
git branch -D feature-branch

Quick Reference

Essential Commands

# Check status
git status

# Add changes
git add .

# Commit changes
git commit -m "type: description"

# Push changes
git push origin branch-name

# Pull changes
git pull origin branch-name

# Create branch
git checkout -b branch-name

# Switch branch
git checkout branch-name

# Merge branch
git merge branch-name

# Delete branch
git branch -d branch-name

Versioning Commands

# Check version
npm version

# Bump version
npm version patch|minor|major

# Run version script
./scripts/version.sh patch|minor|major|prerelease

# List tags
git tag -l

# Show tag
git show v2.0.0

Release Commands

# Quick release
./scripts/version.sh minor && git push origin main && git push origin v$(npm version --json | jq -r '.better-planner')

# Check release status
git log --oneline -10

# Verify tags
git show-ref --tags

📚 Related Files: CHANGELOG.md, VERSION.md, scripts/version.sh 🔧 Scripts: ./scripts/version.sh [patch|minor|major|prerelease] 📋 Workflow: Feature → Review → Merge → Release