From e2737855a3d3544e7a44ba8384be1e206e96c40f Mon Sep 17 00:00:00 2001
From: "Danilo M." <danix@danix.xyz>
Date: Fri, 17 Apr 2026 15:51:27 +0200
Subject: cleanup of the working tree. Created docs/{policies,reports} folders
 to keep documentation organized

---
 docs/policies/GIT-WORKFLOW.md | 485 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 485 insertions(+)
 create mode 100644 docs/policies/GIT-WORKFLOW.md

(limited to 'docs/policies/GIT-WORKFLOW.md')

diff --git a/docs/policies/GIT-WORKFLOW.md b/docs/policies/GIT-WORKFLOW.md
new file mode 100644
index 0000000..b421f83
--- /dev/null
+++ b/docs/policies/GIT-WORKFLOW.md
@@ -0,0 +1,485 @@
+# 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.
+
-- 
cgit v1.2.3