# 📚 คู่มือการจัดการ Git Repository และ Branching Strategy

## 🎯 ภาพรวม

เอกสารนี้แนะนำการจัดการ Git repository และ branching strategy สำหรับโปรเจค **Satisfaction Survey System** ที่จะ integrate กับ **ServTrack**

---

## 🌳 Branching Strategy (แนะนำ: Git Flow)

### โครงสร้าง Branch หลัก

```
main (production)
  ├── develop (development)
  │   ├── feature/* (features)
  │   ├── bugfix/* (bug fixes)
  │   └── servtrack-integration/* (ServTrack integration)
  ├── staging (staging/testing)
  └── hotfix/* (urgent fixes)
```

---

## 📋 Branch Types และการใช้งาน

### 1. **main** (Production Branch)
- **วัตถุประสงค์:** Code ที่พร้อมใช้งานจริง (Production)
- **การใช้งาน:**
  - Merge จาก `staging` เมื่อผ่านการทดสอบแล้ว
  - Tag ด้วย version number (v1.0.0, v1.1.0, etc.)
  - **ห้าม commit โดยตรง** (ต้องผ่าน staging)
- **Environment:** Production (integrate กับ ServTrack)

### 2. **develop** (Development Branch)
- **วัตถุประสงค์:** Code สำหรับพัฒนาและทดสอบ
- **การใช้งาน:**
  - Branch หลักสำหรับ development
  - Merge feature branches ที่เสร็จแล้ว
  - Merge bugfix branches
- **Environment:** Development (standalone)

### 3. **staging** (Staging Branch)
- **วัตถุประสงค์:** Code สำหรับทดสอบก่อน production
- **การใช้งาน:**
  - Merge จาก `develop` เมื่อ feature พร้อมทดสอบ
  - ทดสอบ integration กับ ServTrack
  - ทดสอบการทำงานร่วมกันของ features
- **Environment:** Staging (integrate กับ ServTrack staging)

### 4. **feature/** (Feature Branches)
- **วัตถุประสงค์:** พัฒนา feature ใหม่
- **การตั้งชื่อ:** `feature/feature-name`
- **ตัวอย่าง:**
  - `feature/add-export-report`
  - `feature/improve-survey-ui`
  - `feature/add-email-notification`
- **Flow:**
  ```
  develop → feature/xxx → develop
  ```

### 5. **servtrack-integration/** (ServTrack Integration Branches)
- **วัตถุประสงค์:** พัฒนาและทดสอบการ integrate กับ ServTrack
- **การตั้งชื่อ:** `servtrack-integration/feature-name`
- **ตัวอย่าง:**
  - `servtrack-integration/api-endpoints`
  - `servtrack-integration/modal-component`
  - `servtrack-integration/auth-redirect`
- **Flow:**
  ```
  develop → servtrack-integration/xxx → staging → main
  ```

### 6. **bugfix/** (Bug Fix Branches)
- **วัตถุประสงค์:** แก้ไข bug
- **การตั้งชื่อ:** `bugfix/bug-description`
- **ตัวอย่าง:**
  - `bugfix/fix-survey-submission-error`
  - `bugfix/fix-email-sending-issue`
- **Flow:**
  ```
  develop → bugfix/xxx → develop
  ```

### 7. **hotfix/** (Hotfix Branches)
- **วัตถุประสงค์:** แก้ไข bug ฉุกเฉินใน production
- **การตั้งชื่อ:** `hotfix/bug-description`
- **Flow:**
  ```
  main → hotfix/xxx → main + develop
  ```

---

## 🔄 Workflow สำหรับการพัฒนา

### Scenario 1: พัฒนา Feature ใหม่

```bash
# 1. สร้าง feature branch จาก develop
git checkout develop
git pull origin develop
git checkout -b feature/add-new-feature

# 2. พัฒนาและ commit
git add .
git commit -m "feat: add new feature"

# 3. Push ไปยัง remote
git push origin feature/add-new-feature

# 4. สร้าง Pull Request ไปยัง develop
# (ผ่าน GitHub/GitLab interface)

# 5. หลังจาก merge แล้ว
git checkout develop
git pull origin develop
git branch -d feature/add-new-feature  # ลบ branch local
```

### Scenario 2: พัฒนา ServTrack Integration

```bash
# 1. สร้าง integration branch จาก develop
git checkout develop
git pull origin develop
git checkout -b servtrack-integration/api-endpoints

# 2. พัฒนาและ commit
git add .
git commit -m "feat(servtrack): add API endpoints for integration"

# 3. Push ไปยัง remote
git push origin servtrack-integration/api-endpoints

# 4. สร้าง Pull Request ไปยัง staging (ไม่ใช่ develop)
# เพื่อทดสอบ integration ก่อน

# 5. หลังจากทดสอบผ่านแล้ว merge ไป staging
# จากนั้น merge staging → main เมื่อพร้อม production
```

### Scenario 3: Deploy ไป Production

```bash
# 1. Merge staging → main
git checkout main
git pull origin main
git merge staging
git push origin main

# 2. Tag version
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# 3. Merge main → develop (เพื่อ sync code)
git checkout develop
git merge main
git push origin develop
```

### Scenario 4: Hotfix ฉุกเฉิน

```bash
# 1. สร้าง hotfix branch จาก main
git checkout main
git pull origin main
git checkout -b hotfix/critical-bug-fix

# 2. แก้ไขและ commit
git add .
git commit -m "fix: critical bug fix"

# 3. Merge ไป main
git checkout main
git merge hotfix/critical-bug-fix
git push origin main

# 4. Tag version ใหม่
git tag -a v1.0.1 -m "Hotfix version 1.0.1"
git push origin v1.0.1

# 5. Merge กลับไป develop
git checkout develop
git merge main
git push origin develop
```

---

## 🔐 Environment Configuration

### การจัดการ .env สำหรับแต่ละ Branch

#### 1. สร้าง `.env.example` สำหรับแต่ละ environment

**`.env.example`** (Base template)
```env
APP_NAME="Satisfaction Survey"
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost:8000

# Database
DB_CONNECTION=sqlite
DB_DATABASE=database/database.sqlite

# ServTrack Integration
SERVTRACK_INTEGRATED=false
SERVTRACK_BASE_URL=http://localhost:8000
SERVTRACK_LOGIN_URL=http://localhost:8000/login
SERVTRACK_SURVEY_URL=http://localhost:8000/survey

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=mailhog
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="noreply@example.com"
MAIL_FROM_NAME="${APP_NAME}"
```

**`.env.staging.example`** (Staging environment)
```env
APP_NAME="Satisfaction Survey"
APP_ENV=staging
APP_KEY=
APP_DEBUG=false
APP_URL=https://staging.satisfaction-survey.com

# Database
DB_CONNECTION=mysql
DB_HOST=staging-db-host
DB_PORT=3306
DB_DATABASE=satisfaction_survey_staging
DB_USERNAME=staging_user
DB_PASSWORD=staging_password

# ServTrack Integration (Staging)
SERVTRACK_INTEGRATED=true
SERVTRACK_BASE_URL=https://staging.servtrack.com
SERVTRACK_LOGIN_URL=https://staging.servtrack.com/login
SERVTRACK_SURVEY_URL=https://staging.servtrack.com/survey

# Mail Configuration (Staging)
MAIL_MAILER=smtp
MAIL_HOST=staging-mail-host
MAIL_PORT=587
MAIL_USERNAME=staging-mail-user
MAIL_PASSWORD=staging-mail-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="noreply@staging.satisfaction-survey.com"
MAIL_FROM_NAME="${APP_NAME}"
```

**`.env.production.example`** (Production environment)
```env
APP_NAME="Satisfaction Survey"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://satisfaction-survey.com

# Database
DB_CONNECTION=mysql
DB_HOST=production-db-host
DB_PORT=3306
DB_DATABASE=satisfaction_survey_production
DB_USERNAME=production_user
DB_PASSWORD=production_password

# ServTrack Integration (Production)
SERVTRACK_INTEGRATED=true
SERVTRACK_BASE_URL=https://servtrack.com
SERVTRACK_LOGIN_URL=https://servtrack.com/login
SERVTRACK_SURVEY_URL=https://servtrack.com/survey

# Mail Configuration (Production)
MAIL_MAILER=smtp
MAIL_HOST=production-mail-host
MAIL_PORT=587
MAIL_USERNAME=production-mail-user
MAIL_PASSWORD=production-mail-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="noreply@satisfaction-survey.com"
MAIL_FROM_NAME="${APP_NAME}"
```

---

## 📝 Commit Message Convention

ใช้ [Conventional Commits](https://www.conventionalcommits.org/) format:

### Format
```
<type>(<scope>): <subject>

<body>

<footer>
```

### Types
- `feat`: Feature ใหม่
- `fix`: แก้ไข bug
- `docs`: เอกสาร
- `style`: Formatting, missing semicolons, etc.
- `refactor`: Refactoring code
- `test`: เพิ่ม/แก้ไข tests
- `chore`: Maintenance tasks

### Examples

```bash
# Feature
git commit -m "feat(survey): add export report functionality"

# Bug fix
git commit -m "fix(email): fix email sending issue"

# ServTrack integration
git commit -m "feat(servtrack): add API endpoints for integration"

# Documentation
git commit -m "docs: update integration guide"

# Refactoring
git commit -m "refactor(controller): improve code structure"
```

---

## 🏷️ Version Tagging

### Semantic Versioning (SemVer)

Format: `MAJOR.MINOR.PATCH`

- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)

### Examples

```bash
# Version 1.0.0 (Initial release)
git tag -a v1.0.0 -m "Release version 1.0.0"

# Version 1.1.0 (New features)
git tag -a v1.1.0 -m "Release version 1.1.0: Add export report feature"

# Version 1.1.1 (Bug fix)
git tag -a v1.1.1 -m "Release version 1.1.1: Fix email sending issue"

# Version 2.0.0 (Breaking changes)
git tag -a v2.0.0 -m "Release version 2.0.0: Major refactoring"
```

---

## 🔄 Pull Request Workflow

### สำหรับ Feature Branches

1. **สร้าง Pull Request** จาก `feature/xxx` → `develop`
2. **Review Code** โดยทีม
3. **Run Tests** (automated)
4. **Merge** เมื่อ approve แล้ว

### สำหรับ ServTrack Integration

1. **สร้าง Pull Request** จาก `servtrack-integration/xxx` → `staging`
2. **Review Code** โดยทีม
3. **Test Integration** กับ ServTrack staging environment
4. **Merge** เมื่อผ่านการทดสอบแล้ว
5. **Deploy** ไป staging environment
6. **Test** อีกครั้งใน staging
7. **Merge** `staging` → `main` เมื่อพร้อม production

---

## 🚀 Deployment Strategy

### Development Environment
- **Branch:** `develop`
- **Auto-deploy:** เมื่อมี commit ใหม่
- **Environment:** Standalone (ไม่ integrate กับ ServTrack)

### Staging Environment
- **Branch:** `staging`
- **Auto-deploy:** เมื่อ merge จาก `develop` หรือ `servtrack-integration/*`
- **Environment:** Integrate กับ ServTrack staging

### Production Environment
- **Branch:** `main`
- **Manual deploy:** ต้อง approve ก่อน deploy
- **Environment:** Integrate กับ ServTrack production

---

## 📋 Checklist สำหรับการ Setup Repository

### Initial Setup

- [ ] สร้าง repository บน GitHub/GitLab
- [ ] Clone repository
- [ ] สร้าง branch `develop` จาก `main`
- [ ] สร้าง branch `staging` จาก `main`
- [ ] สร้าง `.env.example` files
- [ ] สร้าง `README.md` พร้อม setup instructions
- [ ] ตั้งค่า branch protection rules:
  - [ ] `main`: Require pull request, require approval
  - [ ] `staging`: Require pull request
  - [ ] `develop`: Allow direct push (optional)

### Branch Protection Rules (GitHub)

#### main branch
- ✅ Require pull request reviews
- ✅ Require status checks to pass
- ✅ Require branches to be up to date
- ✅ Do not allow bypassing the above settings

#### staging branch
- ✅ Require pull request reviews
- ✅ Require status checks to pass
- ⚠️ Allow bypassing (for urgent fixes)

#### develop branch
- ⚠️ Optional protection (allow direct push for faster development)

---

## 🔧 Git Hooks (Optional)

### Pre-commit Hook
ตรวจสอบ code quality ก่อน commit:

```bash
#!/bin/sh
# .git/hooks/pre-commit

# Run Laravel Pint (code formatter)
./vendor/bin/pint --test

# Run PHPUnit tests
php artisan test
```

### Pre-push Hook
ตรวจสอบก่อน push:

```bash
#!/bin/sh
# .git/hooks/pre-push

# Run full test suite
php artisan test
```

---

## 📚 Best Practices

### 1. **Branch Naming**
- ✅ ใช้ lowercase และ hyphen: `feature/add-export`
- ❌ หลีกเลี่ยง: `Feature/AddExport`, `feature_add_export`

### 2. **Commit Messages**
- ✅ ใช้ conventional commits format
- ✅ เขียน commit message ที่ชัดเจน
- ❌ หลีกเลี่ยง: "fix bug", "update", "changes"

### 3. **Pull Requests**
- ✅ เขียน description ที่ชัดเจน
- ✅ Link ไปยัง related issues
- ✅ Request review จากทีม

### 4. **Code Review**
- ✅ Review code อย่างละเอียด
- ✅ ให้ feedback ที่เป็นประโยชน์
- ✅ Approve เมื่อ code ดีแล้ว

### 5. **Testing**
- ✅ เขียน tests สำหรับ features ใหม่
- ✅ Run tests ก่อน commit
- ✅ ตรวจสอบว่า tests ผ่านก่อน merge

---

## 🆘 Troubleshooting

### ปัญหา: Merge conflict

```bash
# 1. Update local branch
git checkout develop
git pull origin develop

# 2. Rebase feature branch
git checkout feature/xxx
git rebase develop

# 3. แก้ไข conflicts
# (แก้ไขไฟล์ที่มี conflict)

# 4. Continue rebase
git add .
git rebase --continue

# 5. Force push (ถ้าจำเป็น)
git push origin feature/xxx --force-with-lease
```

### ปัญหา: Accidentally committed to wrong branch

```bash
# 1. สร้าง branch ใหม่จาก commit ปัจจุบัน
git branch feature/correct-branch

# 2. Reset branch เดิม
git checkout wrong-branch
git reset --hard HEAD~1  # หรือ reset ไปยัง commit ที่ต้องการ

# 3. Switch ไป branch ใหม่
git checkout feature/correct-branch
```

---

## 📞 Support

หากมีคำถามหรือต้องการความช่วยเหลือ กรุณาติดต่อทีมพัฒนา

---

**อัปเดตล่าสุด:** 2024-12-19