path: root/docs/policies/GIT-WORKFLOW.md

# Git Workflow Guide

**Effective Date:** 2026-04-28 (production branch added)  
**Policy:** Feature branches merge to `master` (staging). `production` branch is the live deploy target.

---

## Overview

### Three Branches

| Branch | Purpose |
|--------|---------|
| `feature/*`, `week-*` | Development branches. Merge to master when done. |
| `master` | Staging/dev. No deploy hook. Safe for testing and WIP. |
| `production` | Live. Triggers deploy. Only merge from master when ready. |

### Workflow

```
Feature branch (develop, test)
         ↓
      Merge to master (staging, review)
         ↓
      Merge to production (LIVE DEPLOY)
```

### Branch Naming

- Feature branches: `feature/*`, `week-*`, `content/*`, `fix/*`
- Examples: `feature/dark-mode`, `week-5-forms`, `content/article-update`, `fix/button-style`

---

## Feature Branch Workflow

### Step 1: Create Feature Branch (Optional)

For significant work, create a feature branch:

```bash
# Ensure you're on master and up to date
git checkout master
git pull origin master

# Create feature branch
git checkout -b feature/my-feature
# or: git checkout -b week-5-forms

# Verify branch created
git branch -v
```

### Step 2: Implement Changes

While on the feature branch, implement all changes:

```bash
# Make changes to CSS, templates, content, docs
vim themes/danix-xyz-hacker/assets/css/main.css
vim content/en/articles/new-article/index.md

# Rebuild CSS after changes
npm run build

# Test in browser
hugo server

# Check what changed
git status
git diff
```

### 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: Review Changes Before Merge

Before merging to master, review all changes:

```bash
# Show all commits in this branch
git log master..feature/my-feature --oneline

# Show all file changes (diff summary)
git diff --stat master..feature/my-feature

# Show detailed diff for critical files
git diff master..feature/my-feature

# Check git log looks good
git log --oneline -10
```

### Step 5: Test Thoroughly Before Merge

Test everything on the feature branch:

```bash
# Start dev server
hugo server

# Test in browser:
# - Dark mode
# - Light mode
# - Mobile (320px), tablet (768px), desktop (1060px+)
# - Keyboard navigation (Tab, Shift+Tab, Escape)
# - All interactive elements
# - Responsive layouts

# 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 6: Merge to Master

Once testing is complete:

```bash
# Switch to master
git checkout master
git pull origin master

# Merge feature branch
git merge feature/my-feature

# Optional: Delete the feature branch
git branch -d feature/my-feature

# Verify merge
git log --oneline -10

# Push to staging (no deploy yet)
git push origin master
```

### Step 7: Deploy to Production

When master is ready for the live site:

```bash
# Switch to production
git checkout production
git pull origin production

# Merge master into production
git merge master

# This triggers the post-receive hook and live deploy
git push origin production

# Verify deployment
# - Check server logs
# - Test the live site
```

---

## 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.