Buckets:

|
download
raw
10.7 kB

چگونه یک issue خوب بنویسیم[[how-to-write-a-good-issue]]

<CourseFloatingBanner chapter={8} classNames="absolute z-10 right-0 top-0" notebooks={[ {label: "Google Colab", value: "https://colab.research.google.com/github/huggingface/notebooks/blob/master/course/en/chapter8/section5.ipynb"}, {label: "Aws Studio", value: "https://studiolab.sagemaker.aws/import/github/huggingface/notebooks/blob/master/course/en/chapter8/section5.ipynb"}, ]} />

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

وقتی مطمئن هستید که یک باگ در دست دارید، اولین قدم ساختن یک نمونه حداقل قابل تکرار است.

ایجاد یک مثال حداقل قابل تکرار[[creating-a-minimal-reproducible-example]]

مهم است قطعه‌کدی را که باگ را ایجاد می‌کند جدا کنید، چون هیچ‌کس در تیم هاگینگ‌فیس (هنوز) جادوگر نیست و نمی‌تواند چیزی را که نمی‌بیند اصلاح کند. یک مثال حداقلیِ قابل‌بازتولید، همان‌طور که از نامش پیداست، باید قابل‌بازتولید باشد. این یعنی نباید به فایل یا داده‌ی خارجی‌ای که ممکن است در اختیار داشته باشید وابسته باشد. داده‌های مورد استفاده را با مقادیر ساختگی شبیه مقادیر واقعی جایگزین کنید؛ مقادیری که همچنان همان خطا را ایجاد می‌کنند.

🚨 بسیاری از issueهای مخزن 🤗 ترنسفورمرها حل‌نشده باقی مانده‌اند، چون داده‌های لازم برای بازتولید آن‌ها در دسترس نیست.

وقتی چیزی مستقل و کامل دارید، می‌توانید آن را به خطوط کد کمتری کاهش دهید و چیزی بسازید که آن را مثال حداقلیِ قابل‌بازتولید می‌نامیم. این کار کمی تلاش بیشتر می‌خواهد، اما اگر بازتولیدکننده‌ی کوتاه و خوبی برای باگ ارائه دهید، تقریباً حتماً کمک و اصلاحیه دریافت خواهید کرد.

اگر به‌اندازه‌ی کافی راحت هستید، کد منبعی را که باگ در آن رخ می‌دهد بررسی کنید. شاید راه‌حل مشکل را پیدا کنید (و حتی بتوانید برای اصلاح آن یک pull request پیشنهاد دهید)، اما در حالت کلی این کار به نگه‌دارندگان کمک می‌کند هنگام خواندن گزارش شما منشأ مشکل را بهتر بفهمند.

پر کردن الگوی مشکل[[filling-out-the-issue-template]]

هنگام ثبت issue متوجه می‌شوید الگویی برای تکمیل وجود دارد. در اینجا الگوی issueهای 🤗 ترنسفورمرها را دنبال می‌کنیم، اما اگر در مخزن دیگری issue گزارش دهید، همان نوع اطلاعات لازم خواهد بود. الگو را خالی نگذارید: وقت‌گذاشتن برای تکمیل آن، شانس دریافت پاسخ و حل مشکل را به بیشترین مقدار می‌رساند.

در حالت کلی هنگام ثبت issue همیشه مؤدب باشید. این یک پروژه‌ی متن‌باز است؛ بنابراین از نرم‌افزار رایگان استفاده می‌کنید و هیچ‌کس موظف نیست به شما کمک کند. می‌توانید نقدی را که به‌نظر خودتان موجه است در issue بنویسید، اما نگه‌دارندگان ممکن است آن را بد برداشت کنند و برای کمک عجله‌ای نداشته باشند. حتماً آیین‌نامه‌ی رفتاری پروژه را بخوانید.

از جمله اطلاعات محیطی شما[[including-your-environment-information]]

🤗 ترنسفورمرها ابزاری برای دریافت همه‌ی اطلاعات مورد نیاز درباره‌ی محیط شما فراهم می‌کنند. کافی است دستور زیر را در ترمینال وارد کنید:

transformers-cli env

و شما باید چیزی شبیه به این دریافت کنید:

Copy-and-paste the text below in your GitHub issue and FILL OUT the two last points.

- `transformers` version: 4.12.0.dev0
- Platform: Linux-5.10.61-1-MANJARO-x86_64-with-arch-Manjaro-Linux
- Python version: 3.7.9
- PyTorch version (GPU?): 1.8.1+cu111 (True)
- Tensorflow version (GPU?): 2.5.0 (True)
- Flax version (CPU?/GPU?/TPU?): 0.3.4 (cpu)
- Jax version: 0.2.13
- JaxLib version: 0.1.65
- Using GPU in script?: <fill in>
- Using distributed or parallel set-up in script?: <fill in>

همچنین می توانید یک ! را در ابتدای دستور transformers-cli env اضافه کنید تا آن را از یک سلول نوت بوک اجرا کنید و سپس نتیجه را در ابتدای شماره خود کپی و جایگذاری کنید.

برچسب زدن افراد[[tagging-people]]

تگ کردن افراد با تایپ @ و به دنبال آن شناسهٔ گیت‌هاب آن‌ها، به آن‌ها اعلانی ارسال می‌کند تا مشکل شما را ببینند و ممکن است سریع‌تر پاسخ دهند. از این روش با احتیاط استفاده کنید، زیرا افرادی که تگ می‌کنید ممکن است از مطلع شدن از چیزی که هیچ لینک مستقیمی به آن ندارند، خوششان نیاید. اگر فایل‌های منبع مربوط به اشکال خود را بررسی کرده‌اید، باید آخرین فردی را که در خطی که فکر می‌کنید تغییر ایجاد کرده است و مسئول مشکل شماست تگ کنید (می‌توانید این اطلاعات را با مراجعه به همان خط در GitHub، انتخاب آن و سپس کلیک روی «View git blame» پیدا کنید).

در غیر این صورت، قالب پیشنهادهایی برای تگ کردن افراد ارائه می‌دهد. به طور کلی، هرگز بیش از سه نفر را تگ نکنید!

از جمله یک مثال قابل تکرار[[including-a-reproducible-example]]

اگر موفق شده‌اید مثالی مستقل بسازید که باگ را ایجاد می‌کند، اکنون زمان افزودن آن است! خطی شامل سه بک‌تیک و سپس python بنویسید، مانند زیر:

```python

سپس مثال حداقلیِ قابل‌بازتولید خود را درج کنید و در خطی جدید سه بک‌تیک دیگر بنویسید. این کار باعث می‌شود کد شما به‌درستی قالب‌بندی شود.

اگر نتوانستید یک مثال قابل‌بازتولید ایجاد کنید، مراحل رسیدن به مشکل را به‌روشنی توضیح دهید. اگر می‌توانید، پیوندی به یک نوت‌بوک Google Colab که خطا در آن رخ داده است اضافه کنید. هرچه اطلاعات بیشتری ارائه دهید، نگه‌دارندگان بهتر می‌توانند به شما پاسخ دهند.

در همهٔ موارد، باید متن کامل پیام خطایی را که دریافت می‌کنید کپی و جای‌گذاری کنید. اگر در Colab کار می‌کنید، به یاد داشته باشید که ممکن است برخی فریم‌ها در ردپای پشته به‌طور خودکار جمع شوند؛ بنابراین پیش از کپی کردن، آن‌ها را باز کنید. مانند نمونهٔ کد، پیام خطا را بین دو خط شامل سه بک‌تیک قرار دهید تا به‌درستی قالب‌بندی شود.

شرح رفتار مورد انتظار[[describing-the-expected-behavior]]

در چند خط توضیح دهید انتظار داشتید چه چیزی دریافت کنید تا نگه‌دارندگان درک کاملی از مشکل پیدا کنند. این بخش معمولاً کاملاً روشن است و باید در یک جمله بگنجد، اما در برخی موارد ممکن است توضیحات زیادی داشته باشید.

بعد از آن چه؟[[and-then-what]]

پس از ثبت issue، سریع بررسی کنید که همه‌چیز درست به نظر می‌رسد. اگر اشتباهی کرده‌اید، می‌توانید issue را ویرایش کنید یا اگر متوجه شدید مشکل با چیزی که ابتدا تصور می‌کردید متفاوت است، حتی عنوان آن را تغییر دهید.

اگر پاسخی دریافت نمی‌کنید، پیام دادن مکرر به افراد فایده‌ای ندارد. اگر پس از چند روز کسی به شما کمک نکرد، احتمالاً هیچ‌کس نتوانسته است مشکل شما را درک کند. در بازگشت به مثال قابل‌بازتولید تردید نکنید: آیا می‌توانید آن را کوتاه‌تر و دقیق‌تر کنید؟ اگر پس از یک هفته پاسخی نگرفتید، می‌توانید پیامی مؤدبانه برای درخواست کمک بگذارید؛ به‌ویژه اگر issue خود را ویرایش کرده‌اید تا اطلاعات بیشتری دربارهٔ مشکل در آن بگنجانید.

Xet Storage Details

Size:
10.7 kB
·
Xet hash:
ac674327cc9d53e8ee822ef932b04524c945895c85ffe8d3aad0293c161e058e

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.