# مشارکت در آموزش مقدماتی علم داده

از علاقه شما به مشارکت در برنامه آموزشی مقدماتی علم داده سپاسگزاریم! ما از مشارکت‌های جامعه استقبال می‌کنیم.

## فهرست مطالب

- [قوانین رفتاری](../..)
- [چگونه می‌توانم مشارکت کنم؟](../..)
- [شروع به کار](../..)
- [راهنمای مشارکت](../..)
- [فرآیند درخواست ادغام](../..)
- [راهنمای سبک](../..)
- [توافقنامه مجوز مشارکت‌کننده](../..)

## قوانین رفتاری

این پروژه [قوانین رفتاری متن‌باز مایکروسافت](https://opensource.microsoft.com/codeofconduct/) را پذیرفته است.  
برای اطلاعات بیشتر به [پرسش‌های متداول قوانین رفتاری](https://opensource.microsoft.com/codeofconduct/faq/) مراجعه کنید  
یا با [opencode@microsoft.com](mailto:opencode@microsoft.com) برای هرگونه سوال یا نظر اضافی تماس بگیرید.

## چگونه می‌توانم مشارکت کنم؟

### گزارش اشکالات

قبل از ایجاد گزارش اشکال، لطفاً مسائل موجود را بررسی کنید تا از ایجاد موارد تکراری جلوگیری شود. هنگام ایجاد گزارش اشکال، جزئیات بیشتری را ارائه دهید:

- **از عنوانی واضح و توصیفی استفاده کنید**
- **مراحل دقیق برای بازتولید مشکل را شرح دهید**
- **مثال‌های خاص ارائه دهید** (قطعات کد، تصاویر)
- **رفتاری که مشاهده کردید و انتظارات خود را توضیح دهید**
- **جزئیات محیط خود را شامل کنید** (سیستم‌عامل، نسخه پایتون، مرورگر)

### پیشنهاد بهبودها

پیشنهادات برای بهبود‌ها همیشه مورد استقبال قرار می‌گیرند! هنگام پیشنهاد بهبود‌ها:

- **از عنوانی واضح و توصیفی استفاده کنید**
- **توضیحی دقیق از بهبود پیشنهادی ارائه دهید**
- **توضیح دهید چرا این بهبود مفید خواهد بود**
- **هر ویژگی مشابه در پروژه‌های دیگر را فهرست کنید، اگر قابل اجرا باشد**

### مشارکت در مستندات

بهبود مستندات همیشه مورد قدردانی قرار می‌گیرد:

- **اشتباهات تایپی و گرامری را اصلاح کنید**
- **وضوح توضیحات را بهبود دهید**
- **مستندات گم‌شده را اضافه کنید**
- **اطلاعات قدیمی را به‌روزرسانی کنید**
- **مثال‌ها یا موارد استفاده را اضافه کنید**

### مشارکت در کد

ما از مشارکت‌های کدی استقبال می‌کنیم، از جمله:

- **درس‌ها یا تمرین‌های جدید**
- **رفع اشکالات**
- **بهبود نوت‌بوک‌های موجود**
- **مجموعه داده‌ها یا مثال‌های جدید**
- **بهبود‌های برنامه آزمون**

## شروع به کار

### پیش‌نیازها

قبل از مشارکت، مطمئن شوید که موارد زیر را دارید:

1. یک حساب GitHub
2. Git نصب‌شده روی سیستم شما
3. Python 3.7+ و Jupyter نصب‌شده
4. Node.js و npm (برای مشارکت در برنامه آزمون)
5. آشنایی با ساختار برنامه آموزشی

برای دستورالعمل‌های تنظیم دقیق، به [INSTALLATION.md](INSTALLATION.md) مراجعه کنید.

### فورک و کلون

1. **مخزن را فورک کنید** در GitHub  
2. **فورک خود را به‌صورت محلی کلون کنید**:  
   ```bash
   git clone https://github.com/YOUR-USERNAME/Data-Science-For-Beginners.git
   cd Data-Science-For-Beginners
   ```
  
3. **ریموت بالادستی را اضافه کنید**:  
   ```bash
   git remote add upstream https://github.com/microsoft/Data-Science-For-Beginners.git
   ```
  

### ایجاد یک شاخه

یک شاخه جدید برای کار خود ایجاد کنید:

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```
  
کنوانسیون‌های نام‌گذاری شاخه:  
- `feature/` - ویژگی‌ها یا درس‌های جدید  
- `fix/` - رفع اشکالات  
- `docs/` - تغییرات مستندات  
- `refactor/` - بازسازی کد  

## راهنمای مشارکت

### برای محتوای درس

هنگام مشارکت در درس‌ها یا اصلاح درس‌های موجود:

1. **ساختار موجود را دنبال کنید**:  
   - README.md با محتوای درس  
   - نوت‌بوک Jupyter با تمرین‌ها  
   - تکلیف (در صورت وجود)  
   - لینک به آزمون‌های قبل و بعد  

2. **این عناصر را شامل کنید**:  
   - اهداف یادگیری واضح  
   - توضیحات گام‌به‌گام  
   - مثال‌های کد با توضیحات  
   - تمرین‌هایی برای تمرین  
   - لینک به منابع اضافی  

3. **دسترسی‌پذیری را تضمین کنید**:  
   - از زبان واضح و ساده استفاده کنید  
   - متن جایگزین برای تصاویر ارائه دهید  
   - توضیحات کد را شامل کنید  
   - سبک‌های مختلف یادگیری را در نظر بگیرید  

### برای نوت‌بوک‌های Jupyter

1. **تمام خروجی‌ها را قبل از کامیت پاک کنید**:  
   ```bash
   jupyter nbconvert --clear-output --inplace notebook.ipynb
   ```
  
2. **سلول‌های مارک‌داون** با توضیحات را شامل کنید  

3. **از قالب‌بندی یکسان استفاده کنید**:  
   ```python
   # Import libraries at the top
   import pandas as pd
   import numpy as np
   import matplotlib.pyplot as plt
   
   # Use meaningful variable names
   # Add comments for complex operations
   # Follow PEP 8 style guidelines
   ```
  
4. **نوت‌بوک خود را کاملاً قبل از ارسال آزمایش کنید**  

### برای کد پایتون

از راهنمای سبک [PEP 8](https://www.python.org/dev/peps/pep-0008/) پیروی کنید:

```python
# Good practices
import pandas as pd

def calculate_mean(data):
    """Calculate the mean of a dataset.
    
    Args:
        data (list): List of numerical values
        
    Returns:
        float: Mean of the dataset
    """
    return sum(data) / len(data)
```
  

### برای مشارکت‌های برنامه آزمون

هنگام اصلاح برنامه آزمون:

1. **به‌صورت محلی آزمایش کنید**:  
   ```bash
   cd quiz-app
   npm install
   npm run serve
   ```
  
2. **لینتر را اجرا کنید**:  
   ```bash
   npm run lint
   ```
  
3. **ساخت موفقیت‌آمیز باشد**:  
   ```bash
   npm run build
   ```
  
4. **از راهنمای سبک Vue.js و الگوهای موجود پیروی کنید**  

### برای ترجمه‌ها

هنگام افزودن یا به‌روزرسانی ترجمه‌ها:

1. ساختار موجود در پوشه `translations/` را دنبال کنید  
2. از کد زبان به‌عنوان نام پوشه استفاده کنید (مثلاً `fr` برای فرانسوی)  
3. ساختار فایل مشابه نسخه انگلیسی را حفظ کنید  
4. لینک‌های آزمون را به پارامتر زبان به‌روزرسانی کنید: `?loc=fr`  
5. تمام لینک‌ها و قالب‌بندی را آزمایش کنید  

## فرآیند درخواست ادغام

### قبل از ارسال

1. **شاخه خود را با آخرین تغییرات به‌روزرسانی کنید**:  
   ```bash
   git fetch upstream
   git rebase upstream/main
   ```
  
2. **تغییرات خود را آزمایش کنید**:  
   - تمام نوت‌بوک‌های اصلاح‌شده را اجرا کنید  
   - برنامه آزمون را در صورت اصلاح آزمایش کنید  
   - مطمئن شوید تمام لینک‌ها کار می‌کنند  
   - خطاهای املایی و گرامری را بررسی کنید  

3. **تغییرات خود را کامیت کنید**:  
   ```bash
   git add .
   git commit -m "Brief description of changes"
   ```
  
   پیام‌های کامیت واضح بنویسید:  
   - از زمان حال استفاده کنید ("افزودن ویژگی" نه "ویژگی افزوده شد")  
   - از حالت امری استفاده کنید ("انتقال نشانگر به..." نه "نشانگر منتقل شد به...")  
   - خط اول را به 72 کاراکتر محدود کنید  
   - به مسائل و درخواست‌های ادغام مرتبط اشاره کنید  

4. **به فورک خود پوش کنید**:  
   ```bash
   git push origin feature/your-feature-name
   ```
  

### ایجاد درخواست ادغام

1. به [مخزن](https://github.com/microsoft/Data-Science-For-Beginners) بروید  
2. روی "Pull requests" → "New pull request" کلیک کنید  
3. روی "compare across forks" کلیک کنید  
4. فورک و شاخه خود را انتخاب کنید  
5. روی "Create pull request" کلیک کنید  

### قالب عنوان درخواست ادغام

از عناوین واضح و توصیفی با قالب زیر استفاده کنید:

```
[Component] Brief description
```
  
مثال‌ها:  
- `[Lesson 7] Fix Python notebook import error`  
- `[Quiz App] Add German translation`  
- `[Docs] Update README with new prerequisites`  
- `[Fix] Correct data path in visualization lesson`  

### توضیحات درخواست ادغام

در توضیحات درخواست ادغام خود شامل کنید:

- **چه چیزی**: چه تغییراتی ایجاد کردید؟  
- **چرا**: چرا این تغییرات ضروری هستند؟  
- **چگونه**: چگونه تغییرات را پیاده‌سازی کردید؟  
- **آزمایش**: چگونه تغییرات را آزمایش کردید؟  
- **تصاویر**: تصاویر برای تغییرات بصری  
- **مسائل مرتبط**: لینک به مسائل مرتبط (مثلاً "Fixes #123")  

### فرآیند بررسی

1. **بررسی‌های خودکار** روی درخواست ادغام شما اجرا می‌شوند  
2. **نگهدارندگان مشارکت شما را بررسی می‌کنند**  
3. **بازخورد را با کامیت‌های اضافی پاسخ دهید**  
4. پس از تأیید، یک **نگهدارنده درخواست ادغام شما را ادغام می‌کند**  

### پس از ادغام درخواست شما

1. شاخه خود را حذف کنید:  
   ```bash
   git branch -d feature/your-feature-name
   git push origin --delete feature/your-feature-name
   ```
  
2. فورک خود را به‌روزرسانی کنید:  
   ```bash
   git checkout main
   git pull upstream main
   git push origin main
   ```
  

## راهنمای سبک

### مارک‌داون

- از سطوح عنوان یکسان استفاده کنید  
- بین بخش‌ها خطوط خالی قرار دهید  
- از بلوک‌های کد با مشخص‌کننده زبان استفاده کنید:  
  ````markdown
  ```python
  import pandas as pd
  ```
  ````
  
- متن جایگزین برای تصاویر اضافه کنید: `![Alt text](../../translated_images/fa/image.4ee84a82b5e4c9e6651b13fd27dcf615e427ec584929f2cef7167aa99151a77a.png)`  
- طول خطوط را معقول نگه دارید (حدود 80-100 کاراکتر)  

### پایتون

- از راهنمای سبک PEP 8 پیروی کنید  
- از نام‌های متغیر معنادار استفاده کنید  
- به توابع توضیحات اضافه کنید  
- در صورت امکان از نوع‌دهی استفاده کنید:  
  ```python
  def process_data(df: pd.DataFrame) -> pd.DataFrame:
      """Process the input dataframe."""
      return df
  ```
  

### جاوااسکریپت/Vue.js

- از راهنمای سبک Vue.js 2 پیروی کنید  
- از پیکربندی ESLint ارائه‌شده استفاده کنید  
- اجزای ماژولار و قابل استفاده مجدد بنویسید  
- برای منطق پیچیده توضیحات اضافه کنید  

### سازماندهی فایل‌ها

- فایل‌های مرتبط را کنار هم نگه دارید  
- از نام‌های فایل توصیفی استفاده کنید  
- ساختار دایرکتوری موجود را دنبال کنید  
- فایل‌های غیرضروری را کامیت نکنید (.DS_Store، .pyc، node_modules، و غیره)  

## توافقنامه مجوز مشارکت‌کننده

این پروژه از مشارکت‌ها و پیشنهادات استقبال می‌کند. اکثر مشارکت‌ها نیاز دارند که شما  
با توافقنامه مجوز مشارکت‌کننده (CLA) موافقت کنید که اعلام می‌کند شما حق دارید  
و واقعاً حقوق استفاده از مشارکت خود را به ما اعطا می‌کنید. برای جزئیات، به  
https://cla.microsoft.com مراجعه کنید.

هنگامی که یک درخواست ادغام ارسال می‌کنید، یک ربات CLA به‌طور خودکار تعیین می‌کند که آیا شما نیاز دارید  
CLA ارائه دهید و درخواست ادغام را به‌طور مناسب تزئین می‌کند (مثلاً برچسب، نظر). فقط دستورالعمل‌های  
ارائه‌شده توسط ربات را دنبال کنید. شما فقط یک بار این کار را در تمام مخازن استفاده‌کننده از CLA ما انجام خواهید داد.

## سوالات؟

- کانال [Discord #data-science-for-beginners](https://aka.ms/ds4beginners/discord) ما را بررسی کنید  
- به جامعه [Discord](https://aka.ms/ds4beginners/discord) ما بپیوندید  
- مسائل [موجود](https://github.com/microsoft/Data-Science-For-Beginners/issues) و درخواست‌های [ادغام](https://github.com/microsoft/Data-Science-For-Beginners/pulls) را مرور کنید  

## سپاسگزاریم!

مشارکت‌های شما این برنامه آموزشی را برای همه بهتر می‌کند. از اینکه وقت خود را برای مشارکت اختصاص دادید سپاسگزاریم!

---

**سلب مسئولیت**:  
این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما تلاش می‌کنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌ها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئولیتی در قبال سوء تفاهم‌ها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.