From ef16e309cb3d8efa0c813c987d30bb573b20659a Mon Sep 17 00:00:00 2001 From: Developer Date: Thu, 19 Mar 2026 19:44:35 -0400 Subject: [PATCH] docs: Add comprehensive dev branch setup and workflow guide - Add quick start: 3 options to get the dev branch - Document dev branch setup and isolation - Add complete development workflow examples (4 steps) - Include common dev commands and usage - Add troubleshooting guide for dev branch - Explain isolation features (cache, code, visual, version, git) - Guide for merging dev to production --- README.md | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) diff --git a/README.md b/README.md index d49ebb7..3abb797 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,47 @@ --- +## 🚀 Quick Start: How to Get the Dev Branch + +### Option 1: Clone the Dev Branch from Remote + +```bash +# Clone the entire repository and check out dev branch +git clone https://git.mull.lol/cschantz/Linux-Server-Management-Toolkit.git /root/server-toolkit-beta +cd /root/server-toolkit-beta +git checkout dev + +# Verify you're on dev branch +git branch -vv +# Output should show: * dev adcb3b0 [origin/dev] dev: Add BETA branding... + +# Run the dev launcher +./launcher.sh +# You'll see the YELLOW ⚠️ banner with "2.1.0-BETA" +``` + +### Option 2: Switch Existing Toolkit to Dev Branch + +```bash +# If you already have the toolkit cloned +cd /root/server-toolkit +git fetch origin +git checkout dev + +# Verify +git branch -vv +``` + +### Option 3: Use the Pre-Configured Dev Instance (This Directory) + +```bash +# If you're already in /root/server-toolkit-beta/ +git pull origin dev # Get latest dev changes +./launcher.sh # Run the dev version +``` + +--- + ## 📍 Quick Navigation **For Production**: Visit the `main` branch or `/root/server-toolkit/` @@ -26,6 +67,146 @@ --- +## 🔧 Dev Branch Setup & Workflow + +### Understanding the Dev Branch Structure + +**Repository**: `https://git.mull.lol/cschantz/Linux-Server-Management-Toolkit.git` +- **`main` branch** → Production (stable, tested code) +- **`dev` branch** → Development (testing, new features, experiments) + +Both branches exist in the same remote repository but are completely isolated. + +### Development Workflow + +#### 1️⃣ Get the Latest Dev Code + +```bash +# Update your local dev branch with latest remote changes +cd /root/server-toolkit-beta +git fetch origin # Fetch all remote changes +git pull origin dev # Pull latest dev branch code +``` + +#### 2️⃣ Make Changes & Test + +```bash +# Edit files in the dev branch +nano /root/server-toolkit-beta/launcher.sh +nano /root/server-toolkit-beta/modules/security/malware-scanner.sh + +# Test your changes with the dev launcher +/root/server-toolkit-beta/launcher.sh +# You'll see YELLOW banner: "⚠️ 2.1.0-BETA" +``` + +#### 3️⃣ Commit Changes to Dev Branch + +```bash +cd /root/server-toolkit-beta + +# See what you changed +git status +git diff + +# Stage and commit +git add modules/security/malware-scanner.sh +git commit -m "dev: Added feature XYZ to malware scanner" + +# Push to remote dev branch +git push origin dev +``` + +#### 4️⃣ When Ready: Merge to Production + +```bash +# First ensure dev is stable and tested +cd /root/server-toolkit-beta +git log --oneline -5 # View recent commits + +# Switch to production +cd /root/server-toolkit +git checkout main + +# Get latest dev changes +git fetch origin + +# Merge dev into main +git merge origin/dev +# Review the merge carefully! + +# Push to production +git push origin main +``` + +### Common Dev Commands + +```bash +# Check your current branch +git branch -vv +# Shows: * dev adcb3b0 [origin/dev] ... + +# See what's different from production +cd /root/server-toolkit-beta +git log --oneline main..dev # Commits in dev not in main + +# See what's different from last push +git log --oneline origin/dev..dev + +# Revert unwanted changes +git reset --hard origin/dev # Discard local changes, match remote + +# View recent dev commits +git log --oneline -10 + +# Check if dev is up to date with remote +git status +# Should show: "Your branch is up to date with 'origin/dev'" +``` + +### Isolation Features (Why Dev is Safe) + +✅ **Cache Isolation**: Uses `.sysref.beta` (separate from production `.sysref`) +✅ **Code Isolation**: Changes only in `dev` branch until explicitly merged +✅ **Visual Warning**: YELLOW banner with "BETA" label (can't accidentally think it's production) +✅ **Version Distinction**: `2.1.0-BETA` vs `2.1.0` (easy to identify) +✅ **Git Isolation**: `dev` branch tracked separately from `main` + +### Troubleshooting + +**"I'm on the wrong branch"** +```bash +git branch -a # See all branches +git checkout dev # Switch to dev +git branch -u origin/dev # Track origin/dev +``` + +**"Dev is behind remote"** +```bash +git pull origin dev # Get latest changes +``` + +**"I made a mistake and want to start over"** +```bash +git reset --hard origin/dev # Revert to last pushed state +git clean -fd # Remove untracked files +``` + +**"Production (main) got updates, sync dev with main"** +```bash +# Get latest main changes +git fetch origin main + +# See difference +git log --oneline origin/main..dev + +# Merge main into dev +git merge origin/main +git push origin dev # Push merged result +``` + +--- + ## Full Documentation Below Comprehensive multi-panel server management suite supporting cPanel, InterWorx, Plesk, and standalone Apache with modular architecture and intelligent security features.