diff options
Diffstat (limited to 'docs/policies/BRANCHING-POLICY.md')
| -rw-r--r-- | docs/policies/BRANCHING-POLICY.md | 246 |
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 +``` --- |