16 KiB
مشارکت در آموزش مقدماتی علم داده
از علاقه شما به مشارکت در برنامه آموزشی مقدماتی علم داده سپاسگزاریم! ما از مشارکتهای جامعه استقبال میکنیم.
فهرست مطالب
- قوانین رفتاری
- چگونه میتوانم مشارکت کنم؟
- شروع به کار
- راهنمای مشارکت
- فرآیند درخواست ادغام
- راهنمای سبک
- توافقنامه مجوز مشارکتکننده
قوانین رفتاری
این پروژه قوانین رفتاری متنباز مایکروسافت را پذیرفته است.
برای اطلاعات بیشتر به پرسشهای متداول قوانین رفتاری مراجعه کنید
یا با opencode@microsoft.com برای هرگونه سوال یا نظر اضافی تماس بگیرید.
چگونه میتوانم مشارکت کنم؟
گزارش اشکالات
قبل از ایجاد گزارش اشکال، لطفاً مسائل موجود را بررسی کنید تا از ایجاد موارد تکراری جلوگیری شود. هنگام ایجاد گزارش اشکال، جزئیات بیشتری را ارائه دهید:
- از عنوانی واضح و توصیفی استفاده کنید
- مراحل دقیق برای بازتولید مشکل را شرح دهید
- مثالهای خاص ارائه دهید (قطعات کد، تصاویر)
- رفتاری که مشاهده کردید و انتظارات خود را توضیح دهید
- جزئیات محیط خود را شامل کنید (سیستمعامل، نسخه پایتون، مرورگر)
پیشنهاد بهبودها
پیشنهادات برای بهبودها همیشه مورد استقبال قرار میگیرند! هنگام پیشنهاد بهبودها:
- از عنوانی واضح و توصیفی استفاده کنید
- توضیحی دقیق از بهبود پیشنهادی ارائه دهید
- توضیح دهید چرا این بهبود مفید خواهد بود
- هر ویژگی مشابه در پروژههای دیگر را فهرست کنید، اگر قابل اجرا باشد
مشارکت در مستندات
بهبود مستندات همیشه مورد قدردانی قرار میگیرد:
- اشتباهات تایپی و گرامری را اصلاح کنید
- وضوح توضیحات را بهبود دهید
- مستندات گمشده را اضافه کنید
- اطلاعات قدیمی را بهروزرسانی کنید
- مثالها یا موارد استفاده را اضافه کنید
مشارکت در کد
ما از مشارکتهای کدی استقبال میکنیم، از جمله:
- درسها یا تمرینهای جدید
- رفع اشکالات
- بهبود نوتبوکهای موجود
- مجموعه دادهها یا مثالهای جدید
- بهبودهای برنامه آزمون
شروع به کار
پیشنیازها
قبل از مشارکت، مطمئن شوید که موارد زیر را دارید:
- یک حساب GitHub
- Git نصبشده روی سیستم شما
- Python 3.7+ و Jupyter نصبشده
- Node.js و npm (برای مشارکت در برنامه آزمون)
- آشنایی با ساختار برنامه آموزشی
برای دستورالعملهای تنظیم دقیق، به INSTALLATION.md مراجعه کنید.
فورک و کلون
-
مخزن را فورک کنید در GitHub
-
فورک خود را بهصورت محلی کلون کنید:
git clone https://github.com/YOUR-USERNAME/Data-Science-For-Beginners.git cd Data-Science-For-Beginners -
ریموت بالادستی را اضافه کنید:
git remote add upstream https://github.com/microsoft/Data-Science-For-Beginners.git
ایجاد یک شاخه
یک شاخه جدید برای کار خود ایجاد کنید:
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
کنوانسیونهای نامگذاری شاخه:
feature/- ویژگیها یا درسهای جدیدfix/- رفع اشکالاتdocs/- تغییرات مستنداتrefactor/- بازسازی کد
راهنمای مشارکت
برای محتوای درس
هنگام مشارکت در درسها یا اصلاح درسهای موجود:
-
ساختار موجود را دنبال کنید:
- README.md با محتوای درس
- نوتبوک Jupyter با تمرینها
- تکلیف (در صورت وجود)
- لینک به آزمونهای قبل و بعد
-
این عناصر را شامل کنید:
- اهداف یادگیری واضح
- توضیحات گامبهگام
- مثالهای کد با توضیحات
- تمرینهایی برای تمرین
- لینک به منابع اضافی
-
دسترسیپذیری را تضمین کنید:
- از زبان واضح و ساده استفاده کنید
- متن جایگزین برای تصاویر ارائه دهید
- توضیحات کد را شامل کنید
- سبکهای مختلف یادگیری را در نظر بگیرید
برای نوتبوکهای Jupyter
-
تمام خروجیها را قبل از کامیت پاک کنید:
jupyter nbconvert --clear-output --inplace notebook.ipynb -
سلولهای مارکداون با توضیحات را شامل کنید
-
از قالببندی یکسان استفاده کنید:
# 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 -
نوتبوک خود را کاملاً قبل از ارسال آزمایش کنید
برای کد پایتون
از راهنمای سبک PEP 8 پیروی کنید:
# 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)
برای مشارکتهای برنامه آزمون
هنگام اصلاح برنامه آزمون:
-
بهصورت محلی آزمایش کنید:
cd quiz-app npm install npm run serve -
لینتر را اجرا کنید:
npm run lint -
ساخت موفقیتآمیز باشد:
npm run build -
از راهنمای سبک Vue.js و الگوهای موجود پیروی کنید
برای ترجمهها
هنگام افزودن یا بهروزرسانی ترجمهها:
- ساختار موجود در پوشه
translations/را دنبال کنید - از کد زبان بهعنوان نام پوشه استفاده کنید (مثلاً
frبرای فرانسوی) - ساختار فایل مشابه نسخه انگلیسی را حفظ کنید
- لینکهای آزمون را به پارامتر زبان بهروزرسانی کنید:
?loc=fr - تمام لینکها و قالببندی را آزمایش کنید
فرآیند درخواست ادغام
قبل از ارسال
-
شاخه خود را با آخرین تغییرات بهروزرسانی کنید:
git fetch upstream git rebase upstream/main -
تغییرات خود را آزمایش کنید:
- تمام نوتبوکهای اصلاحشده را اجرا کنید
- برنامه آزمون را در صورت اصلاح آزمایش کنید
- مطمئن شوید تمام لینکها کار میکنند
- خطاهای املایی و گرامری را بررسی کنید
-
تغییرات خود را کامیت کنید:
git add . git commit -m "Brief description of changes"پیامهای کامیت واضح بنویسید:
- از زمان حال استفاده کنید ("افزودن ویژگی" نه "ویژگی افزوده شد")
- از حالت امری استفاده کنید ("انتقال نشانگر به..." نه "نشانگر منتقل شد به...")
- خط اول را به 72 کاراکتر محدود کنید
- به مسائل و درخواستهای ادغام مرتبط اشاره کنید
-
به فورک خود پوش کنید:
git push origin feature/your-feature-name
ایجاد درخواست ادغام
- به مخزن بروید
- روی "Pull requests" → "New pull request" کلیک کنید
- روی "compare across forks" کلیک کنید
- فورک و شاخه خود را انتخاب کنید
- روی "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")
فرآیند بررسی
- بررسیهای خودکار روی درخواست ادغام شما اجرا میشوند
- نگهدارندگان مشارکت شما را بررسی میکنند
- بازخورد را با کامیتهای اضافی پاسخ دهید
- پس از تأیید، یک نگهدارنده درخواست ادغام شما را ادغام میکند
پس از ادغام درخواست شما
-
شاخه خود را حذف کنید:
git branch -d feature/your-feature-name git push origin --delete feature/your-feature-name -
فورک خود را بهروزرسانی کنید:
git checkout main git pull upstream main git push origin main
راهنمای سبک
مارکداون
-
از سطوح عنوان یکسان استفاده کنید
-
بین بخشها خطوط خالی قرار دهید
-
از بلوکهای کد با مشخصکننده زبان استفاده کنید:
```python import pandas as pd ``` -
متن جایگزین برای تصاویر اضافه کنید:
 -
طول خطوط را معقول نگه دارید (حدود 80-100 کاراکتر)
پایتون
- از راهنمای سبک PEP 8 پیروی کنید
- از نامهای متغیر معنادار استفاده کنید
- به توابع توضیحات اضافه کنید
- در صورت امکان از نوعدهی استفاده کنید:
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 ما را بررسی کنید
- به جامعه Discord ما بپیوندید
- مسائل موجود و درخواستهای ادغام را مرور کنید
سپاسگزاریم!
مشارکتهای شما این برنامه آموزشی را برای همه بهتر میکند. از اینکه وقت خود را برای مشارکت اختصاص دادید سپاسگزاریم!
سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما تلاش میکنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمههای خودکار ممکن است شامل خطاها یا نادرستیها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، ترجمه حرفهای انسانی توصیه میشود. ما مسئولیتی در قبال سوء تفاهمها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.