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

# Branching Policy

**Effective Date:** 2026-04-28 (production branch added)  
**Status:** ✅ Active

---

## Executive Summary

All work uses feature branches or direct commits to `master` (staging). `production` branch is the deploy target — only merge from `master` when ready to ship to live site. No direct commits to `production`.

**Format for feature branches:** `week-<number>-<description>`, `feature/*`, or other descriptive names  
**Example:** `week-3-cards-nav`, `feature/dark-mode`, `content/about-page-rewrite`

---

## Branch Roles

| Branch | Purpose | Deploy |
|--------|---------|--------|
| `master` | Staging/dev. Feature branches merge here. WIP and testing ok. | No |
| `production` | Live branch. Merges from master only when ready to ship. Protected. | **Yes** |
| Feature branches | Work branches. Merge to master when done. | No |

---

## Why This Approach?

### 1. Safety
`production` is protected from accidental pushes. Only intentional merges from master deploy to live.

### 2. Staging
`master` allows free commits, testing, and experimentation without risk of live deployment.

### 3. Isolation
Feature branches isolate large work, experiments, and reviews before master.

### 4. Flexibility
Small, quick changes can go directly to master. Larger work uses branches.

### 5. Deployment Control
Merge to `production` only when you've tested and are ready. One extra step prevents accidents.

---

## Workflow

### Feature Branch + Staging + Production

```
┌─── feature/my-feature (development)
│    ├─ commit 1: initial implementation
│    ├─ commit 2: fixes and tweaks
│    └─ [TESTED LOCALLY]
│
├─ Merge to master (staging)
│  └─ master now has changes, no deploy yet
│
└─ When ready to ship:
   └─ Merge master → production (triggers live deploy)
```

OR for quick fixes/content:

```
┌─── master (quick commits directly)
│    ├─ commit 1: fix typo
│    ├─ commit 2: update article
│    └─ [TESTED]
│
└─ When ready: merge master → production (triggers deploy)
```

---

## Step-by-Step Instructions

### 1. For Feature Branches

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

# Make changes, test, commit
vim content/en/articles/new-article/index.md
npm run build  # if changing CSS/templates
git add .
git commit -m "feat: add new feature"

# Test thoroughly on this branch
hugo server
```

### 2. For Quick Changes

```bash
# Small fixes, typos, content updates can go straight to master
git checkout master
git pull origin master

# Make changes (CSS, templates, docs, content)
vim content/en/articles/existing/index.md

# Rebuild CSS if needed
npm run build

# Commit
git add .
git commit -m "content: fix typo in article"

# Push to master
git push origin master
```

### 3. Before Merging Branch to Master

```bash
# Review all changes
git diff master..feature/my-feature

# Review commit history
git log master..feature/my-feature --oneline

# View file changes summary
git diff --stat master..feature/my-feature

# Test thoroughly
hugo server
# - All dark/light modes
# - Mobile, tablet, desktop
# - Keyboard navigation
# - All interactive elements

# Check CSS builds without errors
npm run build

# Check for console errors
```

### 4. Merge to Master

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

# Merge feature branch
git merge feature/my-feature

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

# Verify and push
git log --oneline -5
git push origin master
```

### 5. Deploy to Production

```bash
# When master is ready to go live
git checkout production
git pull origin production

# Merge master into production
git merge master

# This triggers the live deploy
git push origin production

# Verify deployment complete (check server log or website)
```

---

## Policy Details

### Feature Branch Creation

- **Source:** Always branch from `master`
- **Naming:** `feature/*`, `week-*`, `content/*`, or descriptive names (lowercase, hyphens)
- **Lifetime:** Keep it reasonable — days to weeks, not months

Examples:
```
feature/dark-mode
week-5-forms
content/new-article
fix/layout-bug
```

### Commits

- **Frequency:** Commit regularly, after each logical unit of work
- **Messages:** Clear, descriptive, following the format from GIT-WORKFLOW.md
- **Size:** Small chunks (not one giant commit), but not one-commit-per-line either

Example commit sequence:
```
feat: add contact form component
feat: add form validation
fix: fix button styling in dark mode
docs: update contact form documentation
```

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

### Master Branch

- **No direct deploys.** Master is staging only.
- **Safe to commit to directly** for small fixes, typos, content updates.
- **Use feature branches** for significant work (theme, layout, major features).
- **No WIP or broken code** — master should always build without errors.

### Production Branch

- **Protected.** Never commit directly. Only merge from master.
- **Deploy trigger.** Every push to production triggers the live rebuild.
- **Deploy command:**
  ```bash
  git checkout production
  git merge master
  git push origin production
  ```
- **One-way merge.** Only master → production. Never production → master.

---

## FAQ

### "Can I commit directly to master?"
Yes, for small fixes, typos, and content updates. For theme work, features, or larger changes, use a branch.

### "What if I commit to master and it breaks something?"
Master should always build. If it breaks, fix it immediately (either in another commit or revert). Do not push broken code to production.

### "Do I have to use 'week-*' branches?"
No. `week-*` is just a naming convention. Use `feature/*`, `content/*`, `fix/*`, or any descriptive name.

### "Can I create sub-branches off a feature branch?"
Generally no. Use clear commit messages for isolation. If you really need to branch off a branch, just keep it simple.

### "What if there's an urgent bug during a feature branch?"
Fix it on the feature branch (if it's part of the work), or fix it on master separately, then merge into the feature branch. Never push a broken feature branch to production.

### "How do I deploy to production?"
Merge master → production and push:
```bash
git checkout production && git merge master && git push origin production
```

---

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