Instruction file imported from aethrox/qsylla (.cursor/rules/git-workflow.mdc). Copyright stays with the author.

Git Workflow & Versioning

Branch Strategy

Branch Types

• main: Production-ready code, always deployable
• develop: Development branch (optional for MVP, use main directly)
• feature/[name]: New features (e.g., feature/course-generation)
• fix/[name]: Bug fixes (e.g., fix/auth-redirect)
• refactor/[name]: Code refactoring (e.g., refactor/api-structure)
• chore/[name]: Maintenance tasks (e.g., chore/update-dependencies)

Branch Naming Examples

feature/add-quiz-generation
fix/course-export-pdf-formatting
refactor/ai-provider-abstraction
chore/upgrade-nextjs-14.2

Commit Message Format

Use Conventional Commits:

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

[optional body]

[optional footer]

Commit Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, no logic change)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks (dependencies, config)
• perf: Performance improvements

Commit Examples

feat(auth): add login page with Supabase integration
fix(api): handle null course response in GET /api/courses/[id]
docs(readme): update setup instructions
chore(deps): upgrade Next.js to 14.2.0
refactor(ai): extract OpenAI client to separate module
perf(db): add index on courses.user_id

Versioning

This project uses Semantic Versioning (SemVer) with automated version management tools.

For versioning, changelog generation, and release automation, see:

• Versioning Scripts Documentation
• Versioning Quick Start Guide

Quick Reference

• Use npm run version:auto-release for automated releases
• Use npm run version:bump [major|minor|patch] for manual version bumps
• Use npm run version:changelog to generate changelog from commits
• Use npm run version:tag to create git tags

High-Level Versioning Strategy

• Format: MAJOR.MINOR.PATCH (e.g., 1.2.3)
• MAJOR: Breaking changes
• MINOR: New features (backwards compatible)
• PATCH: Bug fixes

Commit Guidelines

Best Practices

1. Small, focused commits: One logical change per commit
2. Descriptive messages: Explain "why", not just "what"
3. Reference issues: Include issue numbers when applicable
4. Test before commit: Ensure code runs without errors
5. No WIP commits to main: Use feature branches
6. Meaningful subject: Clear and concise (50 chars max)
7. Detailed body: Use when commit needs explanation (72 chars per line)

Good Commit Examples

feat(course): add drag-and-drop section reordering

Implemented react-beautiful-dnd for intuitive section reordering.
Updates order_index in database on drop.
Includes optimistic UI updates and error handling.

Closes #24

---

fix(export): correct PDF page breaks

Videos were splitting across pages incorrectly.
Now ensures each video starts on a new page if needed.

---

chore(deps): update dependencies to latest versions

- next@14.2.5
- react@18.3.1
- typescript@5.5.3

Bad Commit Examples (Avoid)

fix stuff
update
WIP
changes
bug fix
more work

Pull Request Workflow

Creating a PR

1. Create feature branch from main
2. Make changes and commit
3. Push branch to origin
4. Create PR with descriptive title and description
5. Link related issues
6. Request review (if team exists)

PR Title Format

feat(scope): Brief description of changes

PR Description Template

## Description
Brief summary of changes

## Changes
- Added X feature
- Fixed Y bug
- Updated Z component

## Testing
- [ ] Tested locally
- [ ] All tests passing
- [ ] No console errors

## Related Issues
Closes #123

Merging Strategy

• Squash and merge: For feature branches (keeps history clean)
• Merge commit: For releases (preserves branch history)
• Rebase: Not recommended for MVP (complexity)

Changelog Management

Changelog is automatically generated from git commits using versioning scripts.

Use npm run version:changelog to generate changelog entries. The script:

• Reads commits since last tag
• Categorizes by type (feat, fix, etc.)
• Inserts into CHANGELOG.md in correct format

For detailed changelog management, see Versioning Scripts Documentation.

Pre-Commit Checks

Recommended Checks

# Before committing
npm run lint          # ESLint
npm run type-check    # TypeScript
npm run build         # Ensure build works

Git Hooks

Git hooks are automatically configured via versioning scripts.

To setup git hooks for commit validation:

npm run version:hooks

This installs:

• commit-msg hook: Validates commit messages follow Conventional Commits
• pre-push hook: Runs type-check and lint before pushing

For details, see Versioning Scripts Documentation.

Git Ignore Rules

Ensure .gitignore includes:

# Dependencies
node_modules/
.pnp/

# Environment
.env.local
.env.*.local

# Build
.next/
out/
dist/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Testing
coverage/

# Logs
*.log

Important Rules

Never Commit

• API keys, passwords, tokens
• node_modules directory
• Build artifacts (.next, out, dist)
• Environment files (.env.local)
• Personal IDE settings
• console.log statements in production code

Always Do

• Pull before push (avoid conflicts)
• Test before commit
• Write meaningful commit messages
• Keep commits atomic
• Use versioning scripts for releases (see Versioning Documentation)

Collaboration Guidelines

Code Review Checklist

• Code follows style guide
• No obvious bugs
• Tests added/updated (if applicable)
• Documentation updated
• No breaking changes (or documented)
• Performance considerations addressed
• Security implications reviewed

Conflict Resolution

1. Pull latest changes: git pull origin main
2. Resolve conflicts in editor
3. Test thoroughly
4. Commit resolution: git commit -m "fix: resolve merge conflicts"
5. Push: git push

Release Process

Use the automated release process:

npm run version:auto-release

This handles:

• Running tests and build validation
• Version bumping
• Changelog generation
• Version consistency checking
• Git tag creation

Manual Release Steps

1. Run npm run version:bump [major|minor|patch]
2. Run npm run version:changelog
3. Review generated changelog
4. Run npm run version:tag
5. Push changes and tags: git push && git push --tags

For detailed release workflows, see:

• Versioning Scripts Documentation
• Versioning Quick Start Guide

Post-Release

1. Monitor for issues
2. Prepare hotfix branch if critical bugs found
3. Update documentation
4. Announce to users