Branching Strategies

یک تیم بدون استراتژی branching = آشفتگی. سه مدل رایج وجود دارد: Git Flow، GitHub Flow و Trunk-Based Development. هر کدام برای نوع تیم و پروژه‌ای مناسب‌اند.

چرا استراتژی لازم است؟

وقتی تیم کوچک است (۱-۲ نفر) شاید نیازی نباشد. اما وقتی ۱۰، ۲۰، ۱۰۰ توسعه‌دهنده روی یک پروژه کار می‌کنند، بدون قاعده:

• کسی نمی‌داند چه branch مال چیست
• کد ناقص در main می‌رود
• release‌ها بدون نظم می‌شوند
• hotfix‌ها سخت می‌شوند
• تست و deployment پیچیده می‌شود

Git Flow

Git Flow توسط Vincent Driessen در ۲۰۱۰ معرفی شد. مدلی پیچیده با چند branch ثابت:

main (production-ready)
  ↓
release/v1.2.0 ────────→ tag v1.2.0
  ↑
develop (integration)
  ↑
feature/x  feature/y  feature/z

و زمانی hotfix لازم شود:
main → hotfix/critical-bug → main + develop

Branch‌های Git Flow

چرخه عملی Git Flow

# شروع فیچر
git switch develop
git pull
git switch -c feature/user-authentication

# توسعه
# ...
git commit -m "feat: implement login"
git push -u origin feature/user-authentication

# بعد از تست و review، merge به develop
git switch develop
git merge --no-ff feature/user-authentication
git push origin develop
git branch -d feature/user-authentication

# آماده‌سازی release
git switch -c release/v1.2.0 develop
# آخرین تست‌ها، bug fix‌های جزئی
git commit -m "chore: bump version to 1.2.0"

# release آماده شد
git switch main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin main --tags

git switch develop
git merge --no-ff release/v1.2.0           # برگرداندن fix‌ها به develop
git push origin develop

git branch -d release/v1.2.0

# Hotfix فوری
git switch -c hotfix/critical-security main
git commit -m "fix: SQL injection in search"
git switch main
git merge --no-ff hotfix/critical-security
git tag -a v1.2.1 -m "Hotfix v1.2.1"
git push origin main --tags

git switch develop
git merge --no-ff hotfix/critical-security
git push origin develop
git branch -d hotfix/critical-security

git-flow extension

sudo apt install git-flow

# راه‌اندازی
git flow init

# دستورات
git flow feature start user-auth         # ساخت feature branch
git flow feature finish user-auth        # merge + حذف

git flow release start v1.2.0
git flow release finish v1.2.0           # merge به main + tag + merge به develop

git flow hotfix start critical-bug
git flow hotfix finish critical-bug

مزایا و معایب Git Flow

✅ مزایا

• ساختار واضح برای پروژه‌های با release‌های مشخص
• main همیشه stable
• پشتیبانی از چند نسخه همزمان
• hotfix‌ها سرراست

❌ معایب

• پیچیده برای تیم‌های کوچک
• مناسب CI/CD مدرن نیست
• Continuous Deployment سخت است
• merge‌های زیاد، تاریخچه شلوغ
• برای web apps با deploy روزانه مناسب نیست

GitHub Flow

GitHub Flow ساده‌ترین مدل است. فقط دو اصل:

1. main همیشه deployable است
2. هر کاری روی feature branch، سپس PR، سپس merge

main ─────────────────────────────────→ (همیشه deployable)
  │ ↑     ↑              ↑
  ↓ │     │              │
  feature/x  feature/y  feature/z

چرخه GitHub Flow

# 1. branch جدید از main
git switch main
git pull
git switch -c feature/add-search

# 2. کار + commit + push
git commit -m "..."
git push -u origin feature/add-search

# 3. PR باز کن
# 4. CI تست‌ها سبز شدن، review قبول شد
# 5. merge به main
# 6. deploy خودکار

# 7. حذف branch
git switch main
git pull
git branch -d feature/add-search

مزایا و معایب GitHub Flow

✅ مزایا

• بسیار ساده – یاد گرفتن سریع
• مناسب CI/CD و continuous deployment
• تاریخچه تمیز
• مناسب web apps

❌ معایب

• نیاز به CI قوی (تست خودکار جدی)
• پشتیبانی از چند نسخه سخت
• برای پروژه‌های با release طولانی مناسب نیست

Trunk-Based Development

افراطی‌ترین مدل: همه روی main کار می‌کنند، با commit‌های کوچک و مکرر:

main:  C1 ── C2 ── C3 ── C4 ── C5 ── C6 ──→
       (همه developerها روی main commit می‌کنند)
       (شاید branch‌های short-lived < 1 روز)

اصول Trunk-Based

• همه روی main کار می‌کنند
• commit‌ها هر چند ساعت
• branch‌های feature خیلی کوتاه (< ۲ روز)
• feature flags برای کد نیمه‌کاره
• CI/CD قوی – هر commit deploy می‌شود
• release branch فقط برای محصولات با release ثابت

Feature Flags

برای کد ناقص که نباید فعال باشد:

# feature_flags.py
FLAGS = {
    "new_search": False,
    "dark_mode": True,
}

def is_enabled(flag):
    return FLAGS.get(flag, False)

# در کد
if is_enabled("new_search"):
    return new_search_algorithm(query)
else:
    return old_search(query)

کتابخانه‌های feature flag: LaunchDarkly، Flagsmith، Unleash، یا ساده در config.

مزایا و معایب Trunk-Based

✅ مزایا

• integration مداوم – بدون merge hell
• کد فعلی همیشه به‌روز است
• سرعت بالای deployment
• منطبق با DevOps مدرن

❌ معایب

• نیاز به مهارت بالای تیم
• CI/CD باید بسیار قوی باشد
• feature flags اضافه می‌کنند پیچیدگی
• برای تیم‌های مبتدی سخت

مقایسه

چه مدلی برای پروژه شما؟

• اپلیکیشن موبایل/desktop: Git Flow
• کتابخانه/SDK با versioning: Git Flow
• Web app/SaaS کوچک تا متوسط: GitHub Flow
• Web app بزرگ با تیم بزرگ: Trunk-Based
• پروژه شخصی/کوچک: GitHub Flow

Release Management

Semantic Versioning (SemVer)

استانداردی برای شماره‌گذاری: MAJOR.MINOR.PATCH

• MAJOR: تغییر breaking (سازگار به عقب نیست) – 1.0.0 → 2.0.0
• MINOR: قابلیت جدید (سازگار به عقب) – 1.2.0 → 1.3.0
• PATCH: bug fix – 1.2.3 → 1.2.4

1.0.0    → اولین release stable
1.0.1    → bug fix
1.1.0    → feature جدید (سازگار)
2.0.0    → تغییر breaking
2.0.0-rc.1   → release candidate
2.0.0-beta.1 → beta
2.0.0-alpha.1 → alpha

CalVer – Calendar Versioning

برخی پروژه‌ها به‌جای SemVer از تاریخ استفاده می‌کنند:

2024.01      Ubuntu 24.01
2024.10.5    سال.ماه.patch

CHANGELOG.md

ثبت تغییرات هر نسخه:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Search functionality with filters

### Changed
- Improved login UI

## [1.2.0] - 2026-04-30

### Added
- Dark mode toggle
- Export to PDF

### Fixed
- Login form validation
- Cart total calculation

### Security
- Updated Django to 5.0.4 (CVE-2024-XXXX)

## [1.1.0] - 2026-03-15

### Added
- User profile page
- Email notifications

### Deprecated
- Old API v1 endpoints (will be removed in 2.0)

## [1.0.0] - 2026-02-01

Initial release.

دسته‌بندی استاندارد

• Added: قابلیت جدید
• Changed: تغییر در قابلیت موجود
• Deprecated: قابلیت‌هایی که بزودی حذف می‌شوند
• Removed: قابلیت‌های حذف‌شده
• Fixed: bug fix
• Security: مرتبط با امنیت

Release Notes خوب

## v1.2.0 - دارک مود و export

### ✨ What's New
- 🌙 **Dark Mode**: کلید تغییر تم در navbar
- 📄 **Export to PDF**: گزارش‌ها قابل export به PDF
- 🔍 **Advanced Search**: فیلتر بر اساس تاریخ، دسته، قیمت

### 🐛 Bug Fixes
- مشکل validation در فرم login
- محاسبه نادرست total در سبد خرید

### 🔧 Maintenance
- آپدیت Django به 5.0.4
- بهبود performance دیتابیس (40% سریع‌تر)

### 📚 Documentation
- راهنمای deploy جدید
- API docs به‌روز شد

### 💔 Breaking Changes
- API v1 deprecated شد، از v2 استفاده کنید

### 🙏 Contributors
@alice، @bob، @charlie

محیط‌های مختلف

یک پروژه معمولاً چند محیط دارد:

• development: روی لپ‌تاپ هر developer
• staging/preview: محیط تست شبیه production
• production: محیط واقعی کاربران

map کردن branch‌ها به محیط‌ها

Git Flow:
- develop  → staging
- main     → production

GitHub Flow:
- feature/* → preview environment (هر PR)
- main      → production

Trunk-Based:
- main     → continuous deploy to production
- main     → staging (auto)

بهترین شیوه‌ها

• یک استراتژی انتخاب کنید و در همه پروژه پیاده‌سازی کنید
• مستندسازی کنید (در README یا CONTRIBUTING)
• برای تیم آموزش دهید
• main را همیشه deployable نگه دارید
• SemVer استاندارد را رعایت کنید
• CHANGELOG را با هر release آپدیت کنید
• Release Notes برای کاربران (نه developer‌ها)
• tag همه release‌ها
• feature flags برای کد ناقص

جمع‌بندی

• Git Flow: پیچیده، برای release-based projects
• GitHub Flow: ساده، برای web apps
• Trunk-Based: مدرن، برای CI/CD
• SemVer: MAJOR.MINOR.PATCH
• CHANGELOG.md: تاریخچه تغییرات
• Feature flags برای کد ناقص
• Map کردن branch‌ها به محیط‌ها

در فصل بعد، rebase و stash – دو ابزار قدرتمند برای تاریخچه تمیز و مدیریت کارهای ناتمام.