// chapter_09.md

Tag و Release در GitHub

Tag در Git مثل bookmark است - برای علامت‌گذاری release‌های مهم. در GitHub، tag‌ها به Release تبدیل می‌شوند که شامل release notes، فایل‌های دانلود و asset‌ها هستند.

Tag در Git مثل bookmark است – برای علامت‌گذاری release‌های مهم. در GitHub، tag‌ها به Release تبدیل می‌شوند که شامل release notes، فایل‌های دانلود و asset‌ها هستند.

انواع Tag

نوع	توضیح	استفاده
Lightweight	فقط اشاره به یک commit	bookmark شخصی
Annotated (پیشنهاد)	object کامل با metadata	release‌های public

ساخت Tag

Annotated Tag (پیشنهاد)

# tag در commit فعلی (HEAD)
git tag -a v1.0.0 -m "First stable release"

# tag روی commit خاص
git tag -a v1.0.0 a3f4b2c -m "First stable release"

# tag بدون editor (پیام در command line)
git tag -a v1.0.0 -m "Release notes:
- Added user authentication
- Fixed payment bug
- Updated dependencies"

# اطلاعات tag را ببینید
git show v1.0.0
# tag v1.0.0
# Tagger: Mohammad Ali <you@example.com>
# Date:   Fri May 1 14:30:00 2026
# 
# First stable release
# 
# commit a3f4b2c1...

Lightweight Tag

git tag v1.0.0
git tag v1.0.0 a3f4b2c
# بدون -a، -m

Signed Tag (با GPG)

# tag با امضای GPG برای امنیت بیشتر
git tag -s v1.0.0 -m "Signed release"

# تأیید امضا
git tag -v v1.0.0

لیست و جستجوی Tag

# لیست همه tag‌ها
git tag

# با pattern
git tag -l "v1.*"
git tag -l "v1.0.*"

# با sort (Git 2.0+)
git tag --sort=-creatordate          # جدیدترین اول
git tag --sort=-version:refname      # بر اساس version

# اطلاعات tag
git show v1.0.0

# لیست tag‌ها با پیام
git tag -n
git tag -n9                           # تا 9 خط پیام

Push کردن Tag به GitHub

به صورت پیش‌فرض، git push tag‌ها را نمی‌فرستد:

# push یک tag خاص
git push origin v1.0.0

# push همه tag‌ها
git push origin --tags
git push --tags

# push commit‌ها + tag‌ها همزمان
git push origin main --follow-tags

تنظیم follow-tags پیش‌فرض

git config --global push.followTags true
# حالا git push خودکار tag‌های annotated مرتبط را می‌فرستد

حذف Tag

# حذف local
git tag -d v1.0.0

# حذف از remote
git push origin --delete v1.0.0
# یا
git push origin :refs/tags/v1.0.0

رفتن به یک Tag

# مثل رفتن به یک commit (detached HEAD)
git checkout v1.0.0

# یا با switch
git switch --detach v1.0.0

# ساخت branch از tag
git switch -c bugfix-v1.0 v1.0.0

قراردادهای نامگذاری

الگوهای رایج بر اساس SemVer:

v1.0.0          stable release
v1.0.0-alpha.1  alpha
v1.0.0-beta.2   beta
v1.0.0-rc.1     release candidate

v1.0.1          patch (bug fix)
v1.1.0          minor (feature)
v2.0.0          major (breaking)

# CalVer
v2026.04.30
v2026.05

GitHub Releases

وقتی یک tag را به GitHub push می‌کنید، به‌طور خودکار release نمی‌شود. release یک قابلیت اضافی GitHub است که شامل:

release notes
فایل‌های قابل دانلود (asset‌ها)
متمایز کردن major releases
RSS feed برای دنبال‌کنندگان

ساخت Release از طریق UI

به ریپو در GitHub بروید
سمت راست: Releases → Draft a new release
Tag را انتخاب کنید (یا tag جدید بسازید)
Title (مثلاً “v1.0.0 – Initial Release”)
توضیحات (markdown):

## ✨ What's New

### 🎉 Features
- 🌙 Dark mode toggle
- 📊 Advanced reporting dashboard
- 🔐 Two-factor authentication

### 🐛 Bug Fixes
- Login form validation
- Cart total calculation
- Memory leak in image processing

### 🔧 Maintenance
- Updated dependencies
- Improved test coverage to 85%

## 💔 Breaking Changes

- API v1 endpoints removed (use v2)
- Config format changed - see migration guide

## 📦 Installation

```bash
pip install awesome-package==1.0.0
```

## 🙏 Contributors

Thanks to: @alice، @bob، @charlie

**Full Changelog**: https://github.com/USER/repo/compare/v0.9.0...v1.0.0

Asset‌ها (فایل‌های دانلودی) attach کنید
Mark as pre-release اگر beta است
Mark as latest release
Publish release

ساخت Release با gh CLI

# نصب GitHub CLI (در فصل ۱۴ مفصل)
sudo apt install gh
gh auth login

# ساخت release
gh release create v1.0.0 
  --title "v1.0.0 - First Release" 
  --notes "Release notes here..."

# با asset
gh release create v1.0.0 
  --title "v1.0.0" 
  --notes-file CHANGELOG.md 
  ./dist/*.zip ./dist/*.tar.gz

# release از فایل
gh release create v1.0.0 
  --title "v1.0.0" 
  --notes-file release-notes.md

# pre-release
gh release create v2.0.0-beta.1 
  --prerelease 
  --title "v2.0.0 Beta 1"

# لیست release‌ها
gh release list

# دانلود asset
gh release download v1.0.0

# حذف
gh release delete v1.0.0

Generate Release Notes خودکار

GitHub می‌تواند release notes را خودکار از PR‌ها بسازد:

تنظیم labels

# .github/release.yml
changelog:
  exclude:
    labels:
      - ignore-for-release
    authors:
      - dependabot
  categories:
    - title: 🎉 Breaking Changes
      labels:
        - breaking-change
    - title: ✨ New Features
      labels:
        - feature
        - enhancement
    - title: 🐛 Bug Fixes
      labels:
        - bug
        - fix
    - title: 📚 Documentation
      labels:
        - documentation
    - title: 🔧 Other Changes
      labels:
        - "*"

وقتی release می‌سازید، روی دکمه Generate release notes کلیک کنید. GitHub PR‌های merge شده از آخرین release را بر اساس label‌ها دسته‌بندی می‌کند.

Tag در مقابل Release

ویژگی	Tag	GitHub Release
محل	در Git	در GitHub (UI/API)
محتوا	اشاره به commit	tag + notes + assets
بدون اینترنت	کار می‌کند	نمی‌کند
RSS	ندارد	دارد
دانلود	فقط zip تاریخچه	asset‌های دلخواه

Release Assets

فایل‌هایی که کاربران دانلود می‌کنند (نه از کد منبع):

اپلیکیشن compile شده (.exe، .dmg، .deb)
زیپ‌های pre-built
SDK‌ها
فایل‌های documentation (.pdf، .epub)
media آرشیو شده

آپلود asset

# با CLI
gh release upload v1.0.0 ./dist/app-windows.exe ./dist/app-mac.dmg

# یا در UI: روی release بروید → Edit → Drag & drop

CHANGELOG.md خودکار

ابزارهایی که از commit‌ها CHANGELOG می‌سازند:

conventional-changelog

# نصب
npm install -g conventional-changelog-cli

# تولید CHANGELOG
conventional-changelog -p angular -i CHANGELOG.md -s

# اولین بار
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

git-cliff (Rust-based، سریع)

# نصب
cargo install git-cliff

# با Conventional Commits
git cliff --output CHANGELOG.md

release-please (Google)

به‌صورت خودکار با هر merge، PR release می‌سازد:

# .github/workflows/release-please.yml
on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          release-type: python   # یا node، go، php

Release Hotfix

# سناریو: v1.2.0 منتشر شده، باگ شدید پیدا شد
git switch -c hotfix/v1.2.1 v1.2.0
# fix...
git commit -m "fix: critical security issue (CVE-2026-XXXX)"

# merge به main
git switch main
git merge hotfix/v1.2.1

# tag و release
git tag -a v1.2.1 -m "Hotfix: critical security"
git push origin main --tags

# release در GitHub
gh release create v1.2.1 
  --title "v1.2.1 - Security Hotfix" 
  --notes "🔒 Critical security fix for CVE-2026-XXXX. Please upgrade immediately."

جریان کاری release کامل

# 1. در شاخه main، آماده release
git switch main
git pull

# 2. آپدیت version در فایل‌های پروژه
# Python: setup.py یا pyproject.toml
# Node: package.json
# PHP: composer.json
# آپدیت __version__ یا VERSION

# 3. آپدیت CHANGELOG.md
# (دستی یا با ابزار)

# 4. commit
git add .
git commit -m "chore: release v1.2.0"
git push

# 5. tag
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0

# 6. release در GitHub
gh release create v1.2.0 
  --title "v1.2.0 - دارک مود و export" 
  --generate-notes 
  ./dist/*.zip

# 7. اعلام
# - Twitter، Slack، Discord
# - Mailing list
# - Discord/Telegram channel

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

همیشه annotated tag (با -a)
SemVer رعایت کنید
هر release یک CHANGELOG entry
release notes برای کاربران، نه developer‌ها
asset‌های pre-built برای راحتی کاربران
signed tag برای پروژه‌های critical
اتوماسیون با release-please یا git-cliff
هرگز tag‌های منتشر شده را تغییر ندهید (rotate نکنید)

جمع‌بندی

Tag = اشاره ثابت به یک commit
Annotated tag (با -a) برای release‌های public
Tag‌ها با git push –tags فرستاده می‌شوند
GitHub Release = tag + notes + assets
auto-generate release notes از PR‌ها
release-please برای اتوماسیون کامل
SemVer + CHANGELOG + signed tags = release حرفه‌ای

در فصل بعد، Issues، Labels، Milestones و Projects در GitHub.