docs: add comprehensive guide for keeping feature branches up-to-date

Added new section "Keeping Your Feature Branch Up-to-Date" covering:
- Daily start-of-work routine for syncing with develop
- Merge vs rebase best practices for teams
- Step-by-step conflict resolution guide
- When and how to ask for help with complex conflicts
- Real-world example of multi-day feature work

This addresses common questions from contributors about branch
management and helps prevent large merge conflicts by encouraging
regular syncing with develop.

CONTRIBUTING.md

@@ -239,6 +239,163 @@ git push origin feature/my-feature
 git push --no-verify
 ```
 
+### Keeping Your Feature Branch Up-to-Date
+
+**Best practice for teams:** Sync your feature branch with `develop` regularly to avoid large merge conflicts.
+
+#### Daily Start-of-Work Routine
+
+```bash
+# 1. Get latest changes from develop
+git checkout develop
+git pull origin develop
+
+# 2. Update your feature branch
+git checkout feature/my-feature
+git merge develop
+
+# 3. If there are conflicts (see below), resolve them
+# 4. Continue working
+```
+
+**How often?**
+- Minimum: Once per day (start of work)
+- Better: Multiple times per day if develop is active
+- Always: Before creating your Pull Request
+
+#### Merge vs Rebase: Which to Use?
+
+**For teams of 5+ developers, use `merge` (not `rebase`):**
+
+```bash
+git checkout feature/my-feature
+git merge develop
+```
+
+**Why merge over rebase?**
+- ✅ Safer: Preserves your commit history
+- ✅ Collaborative: Works when multiple people work on the same feature branch
+- ✅ Transparent: Shows when you integrated upstream changes
+- ✅ No force-push: Once you've pushed to origin, merge won't require `--force`
+
+**When to use rebase:**
+- ⚠️ Only if you haven't pushed yet
+- ⚠️ Only if you're the sole developer on the branch
+- ⚠️ You want a cleaner, linear history
+
+```bash
+# Only do this if you haven't pushed yet!
+git checkout feature/my-feature
+git rebase develop
+```
+
+**Never rebase after pushing** - it rewrites history and breaks collaboration.
+
+#### Handling Merge Conflicts
+
+When you run `git merge develop` and see conflicts:
+
+```bash
+$ git merge develop
+Auto-merging app/Http/Controllers/OrderController.php
+CONFLICT (content): Merge conflict in app/Http/Controllers/OrderController.php
+Automatic merge failed; fix conflicts and then commit the result.
+```
+
+**Step-by-step resolution:**
+
+1. **See which files have conflicts:**
+   ```bash
+   git status
+   # Look for "both modified:" files
+   ```
+
+2. **Open conflicted files** - look for conflict markers:
+   ```php
+   <<<<<<< HEAD
+   // Your code
+   =======
+   // Code from develop
+   >>>>>>> develop
+   ```
+
+3. **Resolve conflicts** - edit the file to keep what you need:
+   ```php
+   // Choose your code, their code, or combine both
+   // Remove the <<<, ===, >>> markers
+   ```
+
+4. **Mark as resolved:**
+   ```bash
+   git add app/Http/Controllers/OrderController.php
+   ```
+
+5. **Complete the merge:**
+   ```bash
+   git commit -m "merge: resolve conflicts with develop"
+   ```
+
+6. **Run tests to ensure nothing broke:**
+   ```bash
+   ./vendor/bin/sail artisan test
+   ```
+
+7. **Push the merge commit:**
+   ```bash
+   git push origin feature/my-feature
+   ```
+
+#### When Conflicts Are Too Complex
+
+If conflicts are extensive or you're unsure:
+
+1. **Abort the merge:**
+   ```bash
+   git merge --abort
+   ```
+
+2. **Ask for help** in #engineering Slack:
+   - "I'm merging develop into feature/X and have conflicts in OrderController"
+   - Someone might have context on the upstream changes
+
+3. **Pair program the resolution** - screen share with the person who made the conflicting changes
+
+4. **Alternative: Start fresh** (last resort):
+   ```bash
+   # Create new branch from latest develop
+   git checkout develop
+   git pull origin develop
+   git checkout -b feature/my-feature-v2
+
+   # Cherry-pick your commits
+   git cherry-pick <commit-hash>
+   ```
+
+#### Example: Multi-Day Feature Work
+
+```bash
+# Monday morning
+git checkout develop && git pull origin develop
+git checkout feature/payment-integration
+git merge develop  # Get latest changes
+# Work all day, make commits
+
+# Tuesday morning
+git checkout develop && git pull origin develop
+git checkout feature/payment-integration
+git merge develop  # Sync again (someone added auth changes)
+# Continue working
+
+# Wednesday
+git checkout develop && git pull origin develop
+git checkout feature/payment-integration
+git merge develop  # Final sync before PR
+git push origin feature/payment-integration
+# Create Pull Request
+```
+
+**Result:** Small, manageable syncs instead of one huge conflict on PR day.
+
 ### When to Test Locally
 
 **Always run tests before pushing if you:**