Merge production branch workflow docs into masterrelease_30042026-0853

1 files changed, 145 insertions, 101 deletions

diff --git a/docs/policies/BRANCHING-POLICY.md b/docs/policies/BRANCHING-POLICY.md
index ddc5138..4fd9ce3 100644
--- a/docs/policies/BRANCHING-POLICY.md
+++ b/docs/policies/BRANCHING-POLICY.md
@@ -1,110 +1,137 @@
-# Weekly Branching Policy
+# Branching Policy
 
-**Effective Date:** Week 3 (2026-04-17 onwards)  
+**Effective Date:** 2026-04-28 (production branch added)  
 **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.
+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:** `week-<number>-<description>`  
-**Example:** `week-3-cards-nav`, `week-4-forms-interactions`
+**Format for feature branches:** `week-<number>-<description>`, `feature/*`, or other descriptive names  
+**Example:** `week-3-cards-nav`, `feature/dark-mode`, `content/about-page-rewrite`
 
 ---
 
-## Why Weekly Branching?
+## Branch Roles
 
-### 1. Code Review
-Each week's work can be reviewed as a complete unit before merging to master.
+| 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 |
 
-### 2. Safety
-If issues are discovered, the feature branch can be easily discarded without affecting master. Easy rollback if needed.
+---
+
+## 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
-Each week's work is independent. Less chance of accidental changes or conflicts affecting master.
+Feature branches isolate large work, experiments, and reviews before master.
 
-### 4. Clean History
-Git log shows logical, week-based commits instead of intermingled changes.
+### 4. Flexibility
+Small, quick changes can go directly to master. Larger work uses branches.
 
-### 5. Testing
-Entire week's work can be tested on the feature branch before merging. Catch issues before they affect master.
+### 5. Deployment Control
+Merge to `production` only when you've tested and are ready. One extra step prevents accidents.
 
 ---
 
-## Weekly Workflow
+## Workflow
 
-### Week 3 (and beyond)
+### Feature Branch + Staging + Production
 
 ```
-┌─── master (stable, always works)
+┌─── 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
 │
-├─ 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]
+└─ 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]
 │
-└─ Merge to master when ready
-   └─ master now has Week 3 changes
+└─ When ready: merge master → production (triggers deploy)
 ```
 
 ---
 
 ## Step-by-Step Instructions
 
-### 1. Start of Week
+### 1. For Feature Branches
 
 ```bash
 # Ensure master is up to date
 git checkout master
-git pull origin master  # if using remote
+git pull origin master
 
 # Create feature branch
-git checkout -b week-3-cards-nav
+git checkout -b feature/my-feature
+# or: git checkout -b week-5-new-feature
 
-# Verify branch created
-git branch -v
+# 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. Throughout the Week
+### 2. For Quick Changes
 
 ```bash
-# Make changes (CSS, templates, docs)
-vim themes/danix-xyz-hacker/assets/css/main.css
+# Small fixes, typos, content updates can go straight to master
+git checkout master
+git pull origin master
 
-# Rebuild CSS
-npm run build
+# Make changes (CSS, templates, docs, content)
+vim content/en/articles/existing/index.md
 
-# Test in browser
-hugo server
+# Rebuild CSS if needed
+npm run build
 
-# Commit regularly after each component
+# Commit
 git add .
-git commit -m "feat: add article card component"
+git commit -m "content: fix typo in article"
 
-# Commit again when next component done
-git add .
-git commit -m "feat: add navigation header"
+# Push to master
+git push origin master
 ```
 
-### 3. End of Week (Before Merging)
+### 3. Before Merging Branch to Master
 
 ```bash
 # Review all changes
-git diff master..week-3-cards-nav
+git diff master..feature/my-feature
 
 # Review commit history
-git log master..week-3-cards-nav --oneline
+git log master..feature/my-feature --oneline
 
 # View file changes summary
-git diff --stat master..week-3-cards-nav
+git diff --stat master..feature/my-feature
 
-# Test thoroughly in browser
-# - All dark mode
-# - All light mode
+# Test thoroughly
+hugo server
+# - All dark/light modes
 # - Mobile, tablet, desktop
 # - Keyboard navigation
 # - All interactive elements
@@ -112,72 +139,73 @@ git diff --stat master..week-3-cards-nav
 # 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
+# Check for console errors
 ```
 
 ### 4. Merge to Master
 
-Once testing is complete:
-
 ```bash
 # Switch to master
 git checkout master
+git pull origin master
 
 # Merge feature branch
-git merge week-3-cards-nav
+git merge feature/my-feature
 
 # Optional: Delete feature branch
-git branch -d week-3-cards-nav
+git branch -d feature/my-feature
 
-# Verify merge
+# Verify and push
 git log --oneline -5
+git push origin master
 ```
 
-### 5. Start Next Week
+### 5. Deploy to Production
 
 ```bash
-# Create next week's branch
-git checkout -b week-4-forms-interactions
+# 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
 
-# Continue with Week 4 work...
+# Verify deployment complete (check server log or website)
 ```
 
 ---
 
-## Branching Policy Details
+## Policy Details
 
-### Branch Creation
+### Feature Branch Creation
 
 - **Source:** Always branch from `master`
-- **Timing:** At the start of each week
-- **Naming:** `week-<N>-<description>` (lowercase, hyphens)
+- **Naming:** `feature/*`, `week-*`, `content/*`, or descriptive names (lowercase, hyphens)
+- **Lifetime:** Keep it reasonable — days to weeks, not months
 
 Examples:
 ```
-week-3-cards-nav
-week-4-forms-interactions
-week-5-animations-a11y
-week-6-pages-testing
+feature/dark-mode
+week-5-forms
+content/new-article
+fix/layout-bug
 ```
 
-### Commits During Week
+### Commits
 
-- **Frequency:** Commit after each component is complete
-- **Messages:** Clear, descriptive, following format
-- **Size:** Small, logical chunks (not one big commit)
+- **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 commits for Week 3:
+Example commit sequence:
 ```
-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
+feat: add contact form component
+feat: add form validation
+fix: fix button styling in dark mode
+docs: update contact form documentation
 ```
 
 ### Testing Before Merge
@@ -196,33 +224,49 @@ docs: week 3 implementation complete
 - [ ] Color contrast WCAG AA verified
 - [ ] All interactive components working (buttons, menus, etc.)
 
-### Merge to Master
+### Master Branch
 
-**Before merging:**
-1. Review all changes: `git diff master..week-N-...`
-2. Complete testing checklist above
-3. Verify git log is clean and clear
+- **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.
 
-**Merge command:**
-```bash
-git checkout master
-git merge week-N-...
-```
+### Production Branch
 
-**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
+- **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.
 
 ---
 
-## Retroactive Application
+## 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.
 
-**Weeks 1-2** were completed on `master` before this policy was adopted.
+### "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.
 
-**Week 3 onwards** will follow weekly branching policy.
+### "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.
 
-All Week 3+ work will be properly isolated on feature branches.
+### "How do I deploy to production?"
+Merge master → production and push:
+```bash
+git checkout production && git merge master && git push origin production
+```
 
 ---