Issues و GitHub Projects

GitHub فقط جای کد نیست – یک پلتفرم کامل برای مدیریت پروژه است. در این فصل با Issues، Labels، Milestones، Projects (kanban) و Discussions آشنا می‌شویم.

Issues – گزارش و پیگیری

Issue یک “تیکت” است که می‌تواند:

• گزارش باگ
• درخواست فیچر
• سوال
• task برای انجام
• discussion درباره طراحی

ساخت Issue

1. به ریپو بروید → tab Issues
2. New issue
3. عنوان واضح و کوتاه
4. شرح با Markdown
5. اختیاری: Assignees، Labels، Milestone، Projects
6. Submit new issue

قالب یک Issue خوب

## شرح مشکل

وقتی روی دکمه "ثبت سفارش" کلیک می‌کنیم، صفحه سفید می‌شود و خطا در console می‌آید.

## مراحل بازتولید

1. به صفحه `/cart` بروید
2. حداقل یک محصول اضافه کنید
3. روی "ثبت سفارش" کلیک کنید
4. مشاهده می‌کنید: صفحه سفید + خطا در console

## رفتار مورد انتظار

باید به صفحه پرداخت برود.

## رفتار فعلی

صفحه سفید با خطای: `TypeError: Cannot read property 'total' of undefined`

## محیط

- Browser: Chrome 120
- OS: Windows 11
- نسخه اپ: v1.2.0

## Screenshots

(ضمیمه شده)

## اطلاعات اضافی

این مشکل از زمان merge شدن PR #234 شروع شده.

Issue Templates

برای استانداردسازی، می‌توانید قالب از پیش تعریف کنید:

روش ۱: Markdown Templates

.github/ISSUE_TEMPLATE/
├── bug_report.md
├── feature_request.md
└── question.md

<!-- .github/ISSUE_TEMPLATE/bug_report.md -->
---
name: 🐛 Bug Report
about: گزارش یک باگ
title: "[BUG] "
labels: bug
assignees: ''
---

## شرح باگ

شرح کوتاه...

## مراحل بازتولید

1. ...
2. ...

## رفتار مورد انتظار vs فعلی

## محیط

- Browser:
- OS:
- نسخه:

## Screenshot

روش ۲: YAML Forms (مدرن‌تر)

قابلیت validate و فیلدهای ساختاریافته:

# .github/ISSUE_TEMPLATE/bug_report.yml
name: 🐛 Bug Report
description: گزارش یک باگ
title: "[BUG] "
labels: ["bug", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        لطفاً اطلاعات کامل دهید تا بتوانیم سریع‌تر مشکل را حل کنیم.

  - type: input
    id: version
    attributes:
      label: نسخه
      description: کدام نسخه را استفاده می‌کنید؟
      placeholder: v1.2.0
    validations:
      required: true

  - type: dropdown
    id: browsers
    attributes:
      label: Browser
      options:
        - Chrome
        - Firefox
        - Safari
        - Edge
        - Other
    validations:
      required: true

  - type: textarea
    id: description
    attributes:
      label: شرح باگ
      description: چه اتفاقی افتاد؟
    validations:
      required: true

  - type: textarea
    id: steps
    attributes:
      label: مراحل بازتولید
      placeholder: |
        1. ...
        2. ...

  - type: checkboxes
    id: checks
    attributes:
      label: قبل از submit
      options:
        - label: issue‌های موجود را جستجو کرده‌ام
          required: true
        - label: نسخه آخر را تست کرده‌ام
          required: true

config.yml

# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: 💬 سوال در Discussions
    url: https://github.com/USER/repo/discussions
    about: برای سوال‌ها از Discussions استفاده کنید
  - name: 🔒 گزارش امنیتی
    url: mailto:security@example.com
    about: مشکلات امنیتی را خصوصی گزارش دهید

Labels – دسته‌بندی

Labels به Issues و PR‌ها کمک می‌کنند دسته‌بندی شوند:

Labels استاندارد

نوع:
🐛 bug
✨ enhancement / feature
📚 documentation
❓ question
🔧 maintenance
🎨 refactor
⚡ performance
🧪 test

اولویت:
🔴 priority: critical
🟠 priority: high
🟡 priority: medium
🟢 priority: low

وضعیت:
🟦 needs-triage
🟪 in-progress
🟧 blocked
✅ ready-for-review

دیگر:
🟢 good first issue
🆘 help wanted
💔 breaking change
🚫 wontfix
🔄 duplicate
❌ invalid

مدیریت Labels

# در GitHub: Issues → Labels → New label
# نام، توضیح، رنگ

# با gh CLI
gh label create bug --color "d73a4a" --description "Something isn't working"
gh label list
gh label edit bug --color "ee0000"
gh label delete bug

Sync labels بین ریپوها

# ابزار github-label-sync
npm install -g github-label-sync

# ساخت labels.json استاندارد
# sync با ریپو
github-label-sync --access-token $GITHUB_TOKEN 
                  --labels labels.json 
                  USER/repo

Milestones – گروه‌بندی Issue

Milestone یک هدف مشخص با تاریخ پایان:

Milestone: v1.2.0 (due 2026-05-15)
├── Issue #234: Add dark mode      [closed]
├── Issue #235: Improve search     [open]
├── Issue #236: Fix login bug      [closed]
└── Issue #237: Update docs        [open]

Progress: 50% (2/4 closed)

ساخت Milestone

1. Issues → Milestones → New milestone
2. عنوان (مثلاً v1.2.0 یا Sprint 5)
3. Due date (اختیاری)
4. توضیحات

اختصاص Issue به Milestone

در صفحه Issue، در sidebar، روی “Milestone” کلیک کنید و انتخاب کنید.

Assignees

هر Issue می‌تواند به چند نفر assigned شود:

• در sidebar Issue: Assignees
• تا 10 نفر
• کسانی که notification می‌گیرند

Auto-assign

# .github/auto_assign.yml
addAssignees: true
addReviewers: true
numberOfReviewers: 2
reviewers:
  - alice
  - bob
  - charlie

GitHub Projects

یک Kanban board برای مدیریت کار:

┌──────────┬────────────┬────────────┬──────────┐
│ Backlog  │ In Progress│ In Review  │ Done     │
├──────────┼────────────┼────────────┼──────────┤
│ #234     │ #237       │ #235       │ #230     │
│ #240     │ #239       │            │ #231     │
│ #241     │            │            │ #232     │
└──────────┴────────────┴────────────┴──────────┘

Projects v2 (مدرن)

Projects v2 (که همان GitHub Projects (beta) بود) جایگزین قدیمی شده. ویژگی‌ها:

• چند view: Board، Table، Roadmap
• فیلدهای سفارشی (custom fields)
• اتوماسیون
• cross-repo (Issues از چند ریپو در یک Project)
• filter‌های قدرتمند

ساخت Project

1. در حساب یا organization: Projects → New project
2. قالب انتخاب کنید (Board، Roadmap، …)
3. نام و توضیحات
4. Create project

اضافه کردن Issue

# روی + در ستون → جستجوی Issue
# یا در صفحه Issue: sidebar → Projects → انتخاب
# یا با gh
gh project item-add 5 --owner USER --url https://github.com/USER/repo/issues/123

Custom Fields

فیلدهای سفارشی برای دسته‌بندی:

• Status: Todo، In Progress، Done
• Priority: Low، Medium، High
• Sprint: Sprint 1، Sprint 2، …
• Estimate: 1، 2، 3، 5، 8 (story points)
• Date: deadline

Views

• Board: Kanban
• Table: spreadsheet-like
• Roadmap: timeline با تاریخ‌ها

اتوماسیون Projects

Project می‌تواند خودکار با وقایع reaction نشان دهد:

• Issue باز شد → اضافه به Backlog
• Issue assigned → انتقال به In Progress
• PR open شد → انتقال به In Review
• PR merged → انتقال به Done
• Issue closed → انتقال به Done

built-in workflows

در project settings → Workflows:

• Auto-add to project
• Item added to project
• Item closed
• Item reopened
• Pull request merged

GitHub Discussions

برای گفتگوهایی که issue نیستند:

• سوالات (Q&A)
• ایده‌ها
• announcements
• polls
• show and tell

فعال‌سازی

1. Settings → General
2. Features → Discussions → ✅
3. tab جدید “Discussions” ظاهر می‌شود

دسته‌بندی‌های پیش‌فرض

Category	کاربرد
📣 Announcements	اطلاعیه‌ها (فقط maintainerها)
💬 General	گفتگوی کلی
💡 Ideas	ایده‌های جدید
🙏 Q&A	پرسش و پاسخ
🗳 Polls	نظرسنجی
🙌 Show and tell	پروژه‌های ساخته‌شده

Issues vs Discussions

Issues	Discussions
Bug، feature	سوال، ایده، گفتگو
قابل assign	قابل reply با threading
قابل بستن (resolved)	قابل علامت‌گذاری به‌عنوان جواب
کار قابل اجرا	گفتگو طولانی

Linking Issues و PR‌ها

اتصال PR به Issue

در توضیحات PR:

Closes #234
Fixes #235
Resolves #236

# همه این کلمات کار می‌کنند:
# close, closes, closed
# fix, fixes, fixed
# resolve, resolves, resolved

وقتی PR merge شود، آن Issue خودکار closed می‌شود.

اشاره به Issue/PR در discussion

#234              # شماره issue/pr در ریپو فعلی
USER/repo#234     # ریپو دیگر
@username         # mention کاربر
@org/team         # mention تیم

جستجو و فیلتر

# در نوار جستجوی Issues
is:issue is:open                       # all open issues
is:issue is:closed                     # closed
is:pr is:merged                        # merged PRs

label:bug                              # بر اساس label
label:bug label:"high priority"        # چند label

assignee:alice                         # assigned به alice
author:bob                             # ساخته‌شده توسط bob

milestone:"v1.2.0"
no:milestone                           # بدون milestone

created:>2026-01-01                    # ساخته‌شده بعد از تاریخ
updated:<2026-04-01                    # آپدیت قبل از تاریخ

is:open is:issue label:bug assignee:@me   # ترکیب
sort:created-desc                      # مرتب‌سازی

Saved searches

filter‌های پرکاربرد را bookmark کنید با URL.

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

• Issue templates برای استانداردسازی
• Labels معنادار (نوع + اولویت + وضعیت)
• Milestone‌ها با تاریخ مشخص
• هر PR به Issue link شود
• Project برای تیم‌های بزرگ – اتوماسیون
• Discussions برای community، Issues برای کار
• “good first issue” برای جذب contributor‌ها
• Stale bot برای issue‌های فراموش شده

جمع‌بندی

• Issues برای bug‌ها، feature‌ها، task‌ها
• Issue Templates (markdown یا YAML forms)
• Labels: نوع + اولویت + وضعیت
• Milestones: گروه‌بندی با deadline
• GitHub Projects: Kanban با چند view
• Discussions: گفتگو و سوال
• Closes #N برای اتصال PR و Issue
• اتوماسیون Project برای کاهش کار دستی

در فصل بعد، GitHub Actions و CI/CD – قدرتمندترین قابلیت GitHub.