path: root/docs/policies/BRANCHING-POLICY.md

# Weekly Branching Policy

**Effective Date:** Week 3 (2026-04-17 onwards)  
**Status:** ✅ Active

---

## Executive Summary

Starting with Week 3, each week of implementation work will use a **feature branch** to isolate changes, enable code review, and ensure safe integration into the main `master` branch.

**Format:** `week-<number>-<description>`  
**Example:** `week-3-cards-nav`, `week-4-forms-interactions`

---

## Why Weekly Branching?

### 1. Code Review
Each week's work can be reviewed as a complete unit before merging to master.

### 2. Safety
If issues are discovered, the feature branch can be easily discarded without affecting master. Easy rollback if needed.

### 3. Isolation
Each week's work is independent. Less chance of accidental changes or conflicts affecting master.

### 4. Clean History
Git log shows logical, week-based commits instead of intermingled changes.

### 5. Testing
Entire week's work can be tested on the feature branch before merging. Catch issues before they affect master.

---

## Weekly Workflow

### Week 3 (and beyond)

```
┌─── master (stable, always works)
│
├─ week-3-cards-nav (feature branch)
│  ├─ commit 1: add card component
│  ├─ commit 2: add navigation header
│  ├─ commit 3: add hamburger menu
│  ├─ commit 4: add breadcrumbs
│  └─ [TESTED & REVIEWED]
│
└─ Merge to master when ready
   └─ master now has Week 3 changes
```

---

## Step-by-Step Instructions

### 1. Start of Week

```bash
# Ensure master is 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
```

### 2. Throughout the Week

```bash
# Make changes (CSS, templates, docs)
vim themes/danix-xyz-hacker/assets/css/main.css

# Rebuild CSS
npm run build

# Test in browser
hugo server

# Commit regularly after each component
git add .
git commit -m "feat: add article card component"

# Commit again when next component done
git add .
git commit -m "feat: add navigation header"
```

### 3. End of Week (Before Merging)

```bash
# Review all changes
git diff master..week-3-cards-nav

# Review commit history
git log master..week-3-cards-nav --oneline

# View file changes summary
git diff --stat master..week-3-cards-nav

# Test thoroughly in browser
# - All dark mode
# - All light mode
# - Mobile, tablet, desktop
# - Keyboard navigation
# - All interactive elements

# Check CSS builds without errors
npm run build

# Check for console errors in browser
# (DevTools → Console)

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

### 4. Merge to Master

Once testing is complete:

```bash
# Switch to master
git checkout master

# Merge feature branch
git merge week-3-cards-nav

# Optional: Delete feature branch
git branch -d week-3-cards-nav

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

### 5. Start Next Week

```bash
# Create next week's branch
git checkout -b week-4-forms-interactions

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

---

## Branching Policy Details

### Branch Creation

- **Source:** Always branch from `master`
- **Timing:** At the start of each week
- **Naming:** `week-<N>-<description>` (lowercase, hyphens)

Examples:
```
week-3-cards-nav
week-4-forms-interactions
week-5-animations-a11y
week-6-pages-testing
```

### Commits During Week

- **Frequency:** Commit after each component is complete
- **Messages:** Clear, descriptive, following format
- **Size:** Small, logical chunks (not one big commit)

Example commits for Week 3:
```
feat: add article card component
feat: add card hover effects (lift, shadow)
feat: add navigation header
feat: add hamburger menu
feat: add breadcrumb navigation
docs: week 3 implementation complete
```

### Testing Before Merge

**Required testing:**
- [ ] Dark mode (all pages, all components)
- [ ] Light mode (toggle, verify all pages)
- [ ] Mobile responsive (320px)
- [ ] Tablet responsive (768px)
- [ ] Desktop responsive (1060px+)
- [ ] Keyboard navigation (Tab, Shift+Tab, Enter, Space, Escape)
- [ ] Focus indicators visible on all interactive elements
- [ ] No hard-coded colors in new CSS
- [ ] CSS builds with no errors (<200ms)
- [ ] No console errors in browser DevTools
- [ ] Color contrast WCAG AA verified
- [ ] All interactive components working (buttons, menus, etc.)

### Merge to Master

**Before merging:**
1. Review all changes: `git diff master..week-N-...`
2. Complete testing checklist above
3. Verify git log is clean and clear

**Merge command:**
```bash
git checkout master
git merge week-N-...
```

**After merge:**
1. Delete feature branch: `git branch -d week-N-...`
2. Verify all changes are in master: `git log --oneline -10`
3. Start next week's branch

---

## Retroactive Application

**Weeks 1-2** were completed on `master` before this policy was adopted.

**Week 3 onwards** will follow weekly branching policy.

All Week 3+ work will be properly isolated on feature branches.

---

## Commit Message Format

### Simple Format
```
<type>: <subject>
```

Example:
```
feat: add article card component
```

### Detailed Format
```
<type>: <subject>

<body>
```

Example:
```
feat: add article card component

- Image with 16:9 aspect ratio
- Title, excerpt, type badge, CTA button
- Hover: lift -2px, shadow enhancement
- Dark/light mode support
- WCAG AA accessible
```

### Types
- `feat:` — New feature (component, layout, page)
- `fix:` — Bug fix
- `style:` — CSS/styling changes
- `refactor:` — Code restructuring
- `docs:` — Documentation changes
- `chore:` — Build, tooling, config

---

## Quick Reference

### Common Commands

```bash
# Create branch
git checkout -b week-3-cards-nav

# Switch branches
git checkout master
git checkout week-3-cards-nav

# View changes
git diff master..week-3-cards-nav
git diff --stat master..week-3-cards-nav

# Commit
git add .
git commit -m "feat: add card component"

# View history
git log master..week-3-cards-nav --oneline
git log --oneline -10

# Merge
git checkout master
git merge week-3-cards-nav

# Delete branch
git branch -d week-3-cards-nav

# List branches
git branch -a
```

See `GIT-WORKFLOW-QUICK-REF.md` for more commands.

---

## FAQ

**Q: Can I work across multiple branches?**  
A: No. Work on one week's feature branch at a time. After merging to master, delete the branch and create a new one for the next week.

**Q: What if master changes while I'm working on Week 3?**  
A: Merge master into your branch: `git checkout week-3-cards-nav && git merge master`. Then resolve any conflicts.

**Q: Can I commit to master directly?**  
A: Not during the week. All changes happen on the feature branch. Merge after testing.

**Q: How long should a feature branch exist?**  
A: One week. Created at start of week, merged to master at end of week, then deleted.

**Q: What if I discover an urgent bug during Week 3?**  
A: Fix it on the feature branch (or fix it on master separately, then merge into feature branch). All work in one week's feature branch.

**Q: Can I create sub-branches off week branches?**  
A: Generally no. Keep it simple: one branch per week. If you need isolation within the week, use clear commit messages instead.

---

## Related Documentation

- **GIT-WORKFLOW.md** — Complete workflow guide with examples
- **GIT-WORKFLOW-QUICK-REF.md** — Common commands quick reference
- **WEEK3-START.md** — Week 3 quick start (includes branching instructions)

---

## Summary

**Weekly branching:**

1. ✅ Create feature branch at week start
2. ✅ Implement work, commit regularly
3. ✅ Test thoroughly before end of week
4. ✅ Review all changes
5. ✅ Merge to master when ready
6. ✅ Delete feature branch
7. ✅ Repeat for next week

This policy ensures clean code, thorough testing, and safe integration.