quicknotes/.cursor/rules/version-control-workflow.mdc

---
description: Standards for Git workflow, branching, pull requests, and code reviews
globs: **/*
---
<rule>
filters:
  - type: event
    pattern: "git|branch|commit|pull_request|merge|rebase"

actions:
  - type: suggest
    message: |
      # Version Control Workflow
      
      ## Branch Naming Convention
      
      1. Format: `<type>/<issue-id>-<short-description>`
         - Example: `feature/123-user-authentication`
         - Example: `fix/456-login-crash`
      
      2. Branch types:
         - `feature/` - New features
         - `fix/` - Bug fixes
         - `refactor/` - Code restructuring
         - `docs/` - Documentation updates
         - `test/` - Test additions/fixes
         - `chore/` - Maintenance tasks
      
      3. Description:
         - Use lowercase
         - Use hyphens instead of spaces
         - Keep it brief but descriptive
         - Include ticket/issue number when applicable
      
      ## Commit Best Practices
      
      1. Follow conventional commits format:
         ```
         <type>(<scope>): <description>
         
         [optional body]
         
         [optional footer(s)]
         ```
         - See the conventional_commits rule for details
      
      2. Keep commits atomic:
         - Each commit should address a single concern
         - Separate logical changes into separate commits
         - Avoid "fix typo" commits - squash them
      
      3. Rebase and cleanup before pushing:
         ```bash
         git rebase -i origin/main
         ```
         - Squash related commits
         - Fix up minor changes
         - Ensure each commit passes tests
      
      ## Pull Request Process
      
      1. PR Template:
         ```markdown
         ## Description
         [Describe the changes made and why]
         
         ## Issue
         Closes #[issue-number]
         
         ## Type of change
         - [ ] Bug fix
         - [ ] New feature
         - [ ] Breaking change
         - [ ] Documentation update
         
         ## Checklist
         - [ ] My code follows style guidelines
         - [ ] I have performed a self-review
         - [ ] I have added tests for new functionality
         - [ ] Tests pass locally
         - [ ] Documentation has been updated
         ```
      
      2. PR Size:
         - Aim for < 400 lines of code changed
         - Break large changes into smaller PRs
         - Each PR should be focused on a single feature/fix
      
      3. PR Lifecycle:
         - Create draft PR for work in progress
         - Request reviews when ready
         - Address all review comments
         - Squash commits before merging
      
      ## Code Review Standards
      
      1. Reviewer Responsibilities:
         - Review within 24 business hours
         - Check functionality, design, and style
         - Provide constructive feedback
         - Approve only if confident in the changes
      
      2. Author Responsibilities:
         - Respond to all comments
         - Explain complex changes
         - Make requested changes or explain why not
         - Keep PR updated with latest main branch
      
      3. Review Comments:
         - Be specific and actionable
         - Explain the "why" not just the "what"
         - Distinguish between required and optional changes
         - Use questions for clarification
      
      ## Merging Strategy
      
      1. Prefer squash merging:
         ```bash
         git checkout main
         git merge --squash feature/123-user-authentication
         git commit -m "feat(auth): implement user authentication (#123)"
         ```
      
      2. Keep main/master branch stable:
         - All tests must pass
         - CI pipeline must be green
         - Required reviews must be approved
      
      3. Delete branches after merging:
         ```bash
         git branch -d feature/123-user-authentication
         ```
      
      ## Git Hooks
      
      1. Pre-commit:
         - Run linters
         - Run tests related to changes
         - Verify commit message format
      
      2. Pre-push:
         - Run full test suite
         - Check for build errors
         - Verify branch is up to date

metadata:
  priority: high
  version: 1.0
</rule>

examples:
  - input: |
      # Bad: Poor branch naming
      git checkout -b fix-login-issue
    output: |
      # Good: Proper branch naming with type and issue number
      git checkout -b fix/123-login-authentication-failure
      
  - input: |
      # Bad: Vague commit message
      git commit -m "fixed stuff"
    output: |
      # Good: Conventional commit with scope and clear description
      git commit -m "fix(auth): resolve login failure when using special characters in password"
      
  - input: |
      # Bad: Direct commits to master/main
      git checkout main
      # make changes
      git commit -m "Quick fix for production"
      git push origin main
    output: |
      # Good: Work on feature branch and create PR
      git checkout -b fix/456-production-hotfix
      # make changes
      git commit -m "fix(core): prevent service crash when database connection fails"
      git push origin fix/456-production-hotfix
      # Then create pull request through UI or API