clitutor/GITHUB_WORKFLOW.md

Interactive CLI learning tool for beginners

# GitHub-Driven Development Workflow for CLI Tutor

## 🎯 Overview
Use GitHub issues as a living document for improvements and PRs for implementation tracking.

## 📋 Issue Management Strategy

### 1. Issue Types (Labels)
- `enhancement`: New features or improvements
- `bug`: Something isn't working correctly
- `documentation`: Documentation improvements
- `refactor`: Code structure improvements
- `content`: Chapter content updates
- `ux`: User experience improvements

### 2. Issue Templates

#### Enhancement Template
```markdown
## Current Behavior
[What exists now]

## Desired Behavior
[What you want to achieve]

## Implementation Notes
[Any specific requirements or constraints]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
```

#### Chapter Improvement Template
```markdown
## Chapter: [Number]
## Section: [Specific lesson/exercise]

## Issues Found
1. [Issue description]
2. [Issue description]

## Proposed Solutions
1. [Solution idea]
2. [Solution idea]

## Priority: [High/Medium/Low]
```

## 🔄 Development Workflow

### Phase 1: Discovery & Documentation
1. **You test chapters/features**
2. **Create issues for each improvement idea**
   - Can be rough notes initially
   - Add thoughts as comments
   - Link related issues

### Phase 2: Refinement
1. **We review issues together**
2. **Add implementation details**
3. **Prioritize with labels/milestones**
4. **Break down large issues**

### Phase 3: Implementation
1. **Create branch from issue**
   ```bash
   gh issue develop <issue-number> --checkout
   ```
2. **Implement with Claude**
3. **Create PR linking to issue**
   ```bash
   gh pr create --title "Fix #<issue>: <description>"
   ```
4. **Review and merge**

## 🏷️ Suggested Labels

```bash
# Create useful labels
gh label create "enhancement" --description "New feature or request" --color "a2eeef"
gh label create "content" --description "Chapter content improvements" --color "7057ff"
gh label create "ux" --description "User experience improvements" --color "ff7261"
gh label create "ready-to-implement" --description "Issue is refined and ready" --color "0e8a16"
gh label create "in-progress" --description "Currently being worked on" --color "fbca04"
```

## 📊 Milestones for Tracking

Create milestones for major goals:
- "Chapter 1-3 Polish" - Current improvements
- "Chapter 4-5 Development" - New content
- "v2.0 Release" - Major feature additions

## 💡 Best Practices

### For You (Issue Creation):
1. **Brain dump freely** - Issues can start as rough notes
2. **Use comments** - Add new thoughts as they come
3. **Link issues** - Reference related problems
4. **Add examples** - Screenshots, command outputs, etc.

### For Our Sessions:
1. **Review open issues** - Start sessions by checking priorities
2. **Work on one issue at a time** - Clear focus
3. **Close via PR** - Use "Fixes #<issue>" in PR description
4. **Document decisions** - Add rationale in PR descriptions

## 🔍 Example Workflow

```bash
# You find an issue while testing
gh issue create --title "Chapter 2: Tab completion needs better visual"

# Later, add more details
gh issue comment <number> --body "Maybe show progressive typing animation?"

# During our session
gh issue develop <number> --checkout
# We implement together
gh pr create --title "Fix #<number>: Add tab completion visualization"

# Auto-closes issue when PR merges
```

## 📈 Progress Tracking

Use GitHub Projects for visual tracking:
1. Create a project board
2. Add automation for issue/PR movement
3. Track progress across chapters

## 🤝 Collaboration Benefits

1. **Async thinking** - You can add ideas anytime
2. **Clear history** - See evolution of features
3. **Searchable** - Find past decisions easily
4. **Public portfolio** - Shows iterative development process