path: root/GIT-WORKFLOW.md

# Git Workflow Guide — Weekly Branching

**Effective Date:** 2026-04-16  
**Policy:** Each week of implementation work starts on a new feature branch for code review and safe integration.

---

## Overview

### Why Weekly Branching?

1. **Code Review** — Review all changes for a week before merging to master
2. **Safety** — Easy to rollback if issues are discovered
3. **Isolation** — Each week's work is independent, reducing merge conflicts
4. **History** — Clean git log with logical week-based commits
5. **Testing** — Test entire week's work on feature branch before merging

### Branch Naming Convention

```
week-<number>-<description>
```

Examples:
- `week-3-cards-nav` (Week 3: Cards & Navigation)
- `week-4-forms-interactions` (Week 4: Forms & Interactive Elements)
- `week-5-animations-a11y` (Week 5: Animations & Accessibility)
- `week-6-pages-testing` (Week 6: Missing Pages & End-to-End Testing)

---

## Weekly Workflow

### Step 1: Create Feature Branch

At the start of each week, create a new feature branch from `master`:

```bash
# Ensure you're on master and up to date
git checkout master
git pull origin master  # (if using remote)

# Create feature branch
git checkout -b week-3-cards-nav

# Verify branch created
git branch -v
```

Output should show:
```
  master           abc1234 commit message
* week-3-cards-nav abc1234 commit message
```

The `*` indicates you're on the new branch.

### Step 2: Implement Week's Work

While on the feature branch, implement all changes for the week:

```bash
# Make changes to CSS, templates, documentation
vim themes/danix-xyz-hacker/assets/css/main.css
vim themes/danix-xyz-hacker/layouts/partials/...

# Rebuild CSS after changes
npm run build

# Test in browser
hugo server

# Check what changed
git status
git diff themes/danix-xyz-hacker/assets/css/main.css
```

### Step 3: Commit Regularly

Commit after completing each component or logical chunk:

```bash
# Stage specific files
git add themes/danix-xyz-hacker/assets/css/main.css
git add themes/danix-xyz-hacker/layouts/partials/card.html

# Commit with clear message
git commit -m "feat: add article card component with hover effects"

# Or use commit message with body for detailed explanation
git commit -m "feat: add article card component

- Image with 16:9 aspect ratio
- Title, excerpt, badge, button
- Hover: lift -2px, shadow enhancement
- Dark/light mode support
- Mobile-first responsive design"
```

### Step 4: Daily Progress Tracking

Update memory at end of each day during the week:

```bash
# Create/update memory file
cat > /path/to/.claude/projects/.../memory/week3_progress.md << 'EOF'
# Week 3 Progress

**Date:** 2026-04-17
**Status:** In progress (Day 1)

## Completed Today
- [x] Article card CSS
- [x] Card integration into templates
- [x] Responsive testing

## Tomorrow
- [ ] Navigation header
- [ ] Hamburger menu
EOF

git add memory/week3_progress.md
git commit -m "docs: update week 3 progress (day 1)"
```

### Step 5: Review Changes at End of Week

Before merging back to master, review all changes:

```bash
# Show all commits in this week
git log master..week-3-cards-nav --oneline

# Show all file changes (diff summary)
git diff --stat master..week-3-cards-nav

# Show detailed diff for CSS
git diff master..week-3-cards-nav themes/danix-xyz-hacker/assets/css/main.css

# Show detailed diff for specific template
git diff master..week-3-cards-nav themes/danix-xyz-hacker/layouts/partials/
```

Example output:
```
abc1234 feat: add article card component
def5678 feat: add navigation header
ghi9012 feat: add hamburger menu
jkl3456 feat: add breadcrumb navigation
mno7890 docs: update week 3 completion report

 themes/danix-xyz-hacker/assets/css/main.css        | +180 -0
 themes/danix-xyz-hacker/layouts/partials/card.html | +45  -0
 themes/danix-xyz-hacker/layouts/partials/nav.html  | +32  -0
 WEEK3-IMPLEMENTATION.md                            | +200 -0
 3 files changed, 457 insertions(+)
```

### Step 6: Test Thoroughly

Before merging, test everything on the feature branch:

```bash
# Start dev server
hugo server

# Test in browser:
# - Dark mode (several pages)
# - Light mode (toggle, verify all components)
# - Mobile (320px)
# - Tablet (768px)
# - Desktop (1060px+)
# - Keyboard navigation (Tab, Enter, Escape)
# - All new components interactive

# Run CSS build without errors
npm run build

# Check for console errors
# (Open browser DevTools → Console)
```

### Step 7: Create Summary & Complete Documentation

At end of week, finalize documentation:

```bash
# Create week completion summary
cat > WEEK3-IMPLEMENTATION.md << 'EOF'
# Week 3 Implementation — Card Layouts & Navigation

[detailed implementation report]
EOF

# Update memory with completion record
cat > memory/week3_complete.md << 'EOF'
---
name: Week 3 Complete: Cards & Navigation
description: Article card component, navigation header, hamburger menu, breadcrumbs
type: project
---

[completion details]
EOF

# Commit documentation
git add WEEK3-IMPLEMENTATION.md memory/week3_complete.md
git commit -m "docs: week 3 implementation complete"
```

### Step 8: Merge Back to Master

Once testing is complete and you're satisfied with all changes:

```bash
# Switch to master
git checkout master

# Merge feature branch (creates merge commit)
git merge week-3-cards-nav

# Or merge with --squash if you want single commit per week
# git merge --squash week-3-cards-nav
# git commit -m "feat: week 3 - card layouts and navigation components"

# Delete the feature branch (optional, good practice)
git branch -d week-3-cards-nav

# Verify merge
git log --oneline -10
```

After merge, master will have all Week 3 changes.

### Step 9: Prepare for Next Week

```bash
# Create Week 4 branch from updated master
git checkout -b week-4-forms-interactions

# Continue with Week 4 work...
```

---

## Commit Message Guidelines

### Format

```
<type>: <subject>

<body>

<footer>
```

### Type

- `feat:` — New feature (component, layout, page)
- `fix:` — Bug fix
- `refactor:` — Code restructuring without functionality change
- `docs:` — Documentation only
- `style:` — CSS/styling changes
- `test:` — Test-related
- `chore:` — Build, tooling, dependencies

### Subject

- Start with lowercase
- Use imperative mood ("add" not "added")
- Max 50 characters
- No period at end

### Body (Optional)

- Explain what and why, not how
- Wrap at 72 characters
- Separate from subject with blank line

### Examples

```
feat: add article card component

- Image with 16:9 aspect ratio, responsive sizes
- Title, excerpt, type badge, CTA button
- Hover: lift -2px, shadow enhancement
- Dark/light mode support verified
- WCAG AA accessible (color contrast, keyboard nav)
```

```
style: refine button component hover state

Increase opacity change from 0.8 to 0.85 for better visibility.
Add translateY(-1px) for lift effect on hover.
```

```
docs: update week 3 progress report

Completed: Card layout, Navigation header
Next: Hamburger menu, Breadcrumbs
```

---

## Common Git Tasks

### View Changes Before Committing

```bash
# See all unstaged changes
git diff

# See all staged changes
git diff --staged

# See changes in specific file
git diff themes/danix-xyz-hacker/assets/css/main.css
```

### Unstage Changes

```bash
# Unstage single file
git restore --staged themes/danix-xyz-hacker/assets/css/main.css

# Unstage all
git restore --staged .
```

### Discard Changes (Be Careful!)

```bash
# Discard changes to single file
git restore themes/danix-xyz-hacker/assets/css/main.css

# Discard ALL unstaged changes
git restore .
```

### Undo Last Commit (Keep Changes)

```bash
# Soft undo (changes stay staged)
git reset --soft HEAD~1

# Or hard undo (discard changes)
git reset --hard HEAD~1
```

### View Commit History

```bash
# Last 10 commits
git log --oneline -10

# With visual graph
git log --oneline --graph -10

# Full details
git log -1  # Last commit details
```

### Switch Between Branches

```bash
# List all branches
git branch -a

# Switch to existing branch
git checkout week-3-cards-nav

# Create and switch (one command)
git checkout -b week-3-cards-nav
```

---

## Handling Merge Conflicts

If master changes while you're on feature branch:

```bash
# Update master (from remote)
git checkout master
git pull origin master

# Switch back to feature branch
git checkout week-3-cards-nav

# Merge master into your branch
git merge master

# If conflicts occur, resolve them manually
# Then commit the merge
git add .
git commit -m "merge: update week 3 with latest master"
```

---

## Branch Lifecycle

```
master (stable)
  │
  ├─ week-3-cards-nav (feature branch)
  │  ├─ commit: add card component
  │  ├─ commit: add navigation header
  │  ├─ commit: add hamburger menu
  │  └─ [tested, reviewed]
  │
  └─ (merge back to master when ready)
     └─ master now has all week 3 changes
```

---

## Review Checklist

Before merging to master:

- [ ] All components built and tested
- [ ] Dark mode: All components styled
- [ ] Light mode: All components styled
- [ ] Mobile (320px): Responsive
- [ ] Tablet (768px): Responsive
- [ ] Desktop (1060px+): Responsive
- [ ] Keyboard navigation: Working
- [ ] Focus indicators: Visible
- [ ] Color contrast: WCAG AA
- [ ] CSS builds: No errors (<200ms)
- [ ] No hard-coded colors
- [ ] No console errors in browser
- [ ] Documentation: Updated
- [ ] Git log: Clear, readable commit messages
- [ ] Ready to merge: Yes/No

---

## Example: Week 3 Complete

After finishing Week 3 and merging to master:

```bash
# You're on master now
git log --oneline -10

# Output shows:
# abc1234 Merge branch 'week-3-cards-nav'
# def5678 docs: week 3 implementation complete
# ghi9012 feat: add breadcrumb navigation
# jkl3456 feat: add hamburger menu
# mno7890 feat: add navigation header
# pqr1234 feat: add article card component
# stu5678 Week 2 work (previous master state)
```

Now you're ready to start Week 4:

```bash
git checkout -b week-4-forms-interactions
# ... continue with Week 4 work ...
```

---

## Summary

**Weekly Branching Workflow:**

1. ✅ Create feature branch at week start (`git checkout -b week-N-...`)
2. ✅ Implement work, commit regularly with clear messages
3. ✅ Test thoroughly before end of week
4. ✅ Review all changes (`git diff master..week-N-...`)
5. ✅ Update documentation and memory
6. ✅ Merge to master (`git merge week-N-...`)
7. ✅ Delete feature branch (`git branch -d week-N-...`)
8. ✅ Repeat for next week

This workflow keeps work organized, safe, and easy to review.