153 lines
3.5 KiB
Markdown
153 lines
3.5 KiB
Markdown
# Git Checkpoint Commit Format
|
|
|
|
Use this structured format for all checkpoint commits during phased development.
|
|
|
|
---
|
|
|
|
## Template
|
|
|
|
```
|
|
checkpoint: Phase [N] [Status] - [Brief Description]
|
|
|
|
Phase: [N] - [Name]
|
|
Status: [Complete/In Progress/Paused/Blocked]
|
|
Session: [What was accomplished this session]
|
|
|
|
Files Changed:
|
|
- path/to/file.ts (what changed)
|
|
- path/to/another.tsx (what changed)
|
|
|
|
Next: [Concrete next action with file path + line number]
|
|
```
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
### Phase Complete
|
|
|
|
```
|
|
checkpoint: Phase 3 Complete - Tasks API
|
|
|
|
Phase: 3 - Tasks API
|
|
Status: Complete
|
|
Session: Completed all CRUD endpoints and verified functionality
|
|
|
|
Files Changed:
|
|
- src/routes/tasks.ts (all CRUD operations)
|
|
- src/lib/schemas.ts (task validation)
|
|
- src/middleware/validate.ts (validation middleware)
|
|
|
|
Next: Phase 4 - Start building Task List UI component
|
|
```
|
|
|
|
### Context Full Mid-Phase
|
|
|
|
```
|
|
checkpoint: Phase 3 In Progress - Endpoints implemented
|
|
|
|
Phase: 3 - Tasks API
|
|
Status: In Progress
|
|
Session: Implemented GET and POST endpoints, need PATCH/DELETE
|
|
|
|
Files Changed:
|
|
- src/routes/tasks.ts (GET, POST endpoints)
|
|
- src/lib/schemas.ts (task schema)
|
|
|
|
Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47
|
|
```
|
|
|
|
### Blocked or Paused
|
|
|
|
```
|
|
checkpoint: Phase 3 Paused - Need design decision
|
|
|
|
Phase: 3 - Tasks API
|
|
Status: Paused
|
|
Session: Built endpoints but need to decide on tag filtering approach
|
|
|
|
Files Changed:
|
|
- src/routes/tasks.ts (basic endpoints)
|
|
|
|
Next: Decide: client-side tag filtering or add SQL query parameter? Then resume at src/routes/tasks.ts:89
|
|
```
|
|
|
|
### Bug Fix During Verification
|
|
|
|
```
|
|
checkpoint: Phase 3 In Progress - Fixed validation bug
|
|
|
|
Phase: 3 - Tasks API
|
|
Status: In Progress (Verification stage)
|
|
Session: Fixed invalid data returning 500 instead of 400
|
|
|
|
Files Changed:
|
|
- src/middleware/validate.ts (added try-catch for Zod errors)
|
|
|
|
Next: Continue verification - test PATCH and DELETE endpoints
|
|
```
|
|
|
|
---
|
|
|
|
## Guidelines
|
|
|
|
**Status Values**:
|
|
- `Complete` - Phase fully done, all verification passed
|
|
- `In Progress` - Active work, may include stage (Implementation/Verification/Debugging)
|
|
- `Paused` - Temporarily stopped, waiting for decision or external input
|
|
- `Blocked` - Cannot proceed due to blocker (note blocker in Session field)
|
|
|
|
**Session Field**:
|
|
- Focus on WHAT was accomplished, not HOW
|
|
- Be specific enough for future resume
|
|
- Include stage if not obvious (Verification, Debugging)
|
|
|
|
**Files Changed**:
|
|
- List significant files only (not config changes)
|
|
- Briefly note what changed in each file
|
|
- Use relative paths from project root
|
|
|
|
**Next Field**:
|
|
- MUST be concrete (file + line + action)
|
|
- NOT vague ("Continue working on...")
|
|
- Include decision points if relevant
|
|
- File paths should be specific
|
|
|
|
---
|
|
|
|
## Creating Checkpoints
|
|
|
|
**When to checkpoint**:
|
|
- ✅ End of phase (status: Complete)
|
|
- ✅ Context getting full mid-phase (status: In Progress)
|
|
- ✅ Pausing for user decision (status: Paused)
|
|
- ✅ Hitting a blocker (status: Blocked)
|
|
|
|
**How to create**:
|
|
```bash
|
|
# Stage changes
|
|
git add path/to/changed/files
|
|
|
|
# Commit with checkpoint format
|
|
git commit -m "$(cat <<'EOF'
|
|
checkpoint: Phase 3 In Progress - Endpoints implemented
|
|
|
|
Phase: 3 - Tasks API
|
|
Status: In Progress
|
|
Session: Implemented GET and POST endpoints, need PATCH/DELETE
|
|
|
|
Files Changed:
|
|
- src/routes/tasks.ts (GET, POST endpoints)
|
|
- src/lib/schemas.ts (task schema)
|
|
|
|
Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47
|
|
EOF
|
|
)"
|
|
```
|
|
|
|
**After checkpoint**:
|
|
- Update SESSION.md with checkpoint commit hash
|
|
- Push to remote if desired
|
|
- Clear context if needed
|
|
- Resume from "Next" field when continuing
|