پرش به محتویات

افزودن مستندات

ممکن است بهترین نرم‌افزار جهان را داشته باشید - اما اگر هیچ‌کس نداند چگونه از آن استفاده کند، چه فایده‌ای دارد؟ مستندات همیشه قابل بهبود است - و ما به کمک شما نیاز داریم!

فرم‌های مستندسازی

مستندات BeeWare با استفاده از MkDocs و Markdown نوشته می‌شود. ما قصد داریم از چارچوب Diataxis برای ساختاردهی مستندات پیروی کنیم.

چارچوب Diataxis چهار «شکل» مستندسازی را توصیف می‌کند:

  • آموزشگاه - یک تجربه یادگیری هدایت‌شده با یک هدف پروژه مشخص.
  • راهنمای چگونگی انجام کار - دستورالعمل‌هایی که خواننده را به سمت یک هدف یا نتیجهٔ مشخص هدایت می‌کنند.
  • راهنمای موضوع - بحثی درباره یک ایده واحد، که به گونه‌ای توضیح داده شده است که مفاهیم زیربنایی آن روشن باشند.
  • مرجع - توضیحات فنی مربوط به APIهای خاص یا سایر رابط‌ها.

قبل از شروع هرگونه مشارکت در مستندسازی، مهم است که مشخص کنید کدام قالب مناسب‌تر است. بسیاری از پیشنهادهای مستندسازی در ابتدا به‌عنوان درخواستی برای «آموزشی درباره‌ی X» توصیف می‌شوند، اما در اغلب موارد آنچه واقعاً مورد نیاز است، راهنمای نحوه انجام کار، راهنمای موضوع یا اطلاعات مرجع بهبود‌یافته است.

به‌عنوان مثال، وظیفه‌ی نوشتن مستندات درباره‌ی پختن کلوچه‌ها را در نظر بگیرید.

آموزش

یک آموزش مقدمه‌ای است، به‌ویژه آن که برای مبتدیان طراحی شده است، و هدف آن باید رساندن خواننده از یک نقطهٔ شروع خالی به یک محصول نهایی باشد. این آموزش نیازمند دستورالعمل‌های بسیار دقیق و توضیحات مفصل است که مراحل را در زمینهٔ مناسب قرار دهد. شما نباید هیچ فرضی دربارهٔ تجربهٔ خواننده با ابزاری که در حال توضیح آن هستید داشته باشید، هرچند فرض بر داشتن مهارت‌های پایه‌ای پایتون معقول است.

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

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

راهنمای نحوه انجام

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

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

راهنمای موضوع

راهنمای موضوع یک موضوع یا ایدهٔ واحد را توصیف می‌کند. ممکن است شامل کد نمونه یا دستورالعمل‌ها باشد، اما تمرکز اصلی آن بر ارائهٔ تصویری کلی از یک مفهوم است. ممکن است شامل نظرات و دیدگاه‌های جایگزین باشد، اما باید بر موضوع خاصِ راهنما تمرکز شود.

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

منبع

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

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

سبک مستندسازی

مستندات BeeWare مطابق دستورالعمل‌های ذکرشده در راهنمای سبک مستندسازی است. این راهنما شامل سبک و قالب‌بندی پایه و فرایند بررسی املایی می‌شود. همچنین جزئیات مختلف نحوی مارک‌داون، مانند نحو لینک مرجع، نکات کار با بلوک‌های کد و مدیریت تصاویر را پوشش می‌دهد.

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

پیشنهاد مستندسازی جدید

پس شما ایده‌ای برای بهبود BeeWare دارید - چگونه آن را برای بررسی ارسال می‌کنید؟

تحقیق کنید

اولین قدم این است که در ردیاب مشکلات BeeWare به دنبال مشکلات ویژگی (مسائلی که با برچسب «enhancement» مشخص شده‌اند)، مشکلات مستندسازی (مسائلی که با برچسب «documentation» مشخص شده‌اند) یا موضوعات بحث بگردید تا ببینید آیا این ایده قبلاً پیشنهاد شده است یا خیر. اگر چنین است و شما زمینه یا ایده‌های جدیدی برای اضافه کردن دارید، آن‌ها را در همان رشته گفتگو موجود درج کنید. اگر برای تحقیق خود به کمک نیاز دارید، می‌توانید در کانال #dev در دیسکورد BeeWare درخواست کمک کنید. ما ممکن است بتوانیم شما را به سمت رشته‌های گفتگو موجود راهنمایی کنیم، زمینه‌هایی را که ممکن است از آن‌ها مطلع نباشید ارائه دهیم، یا ایده شما را به ایده‌ای دیگر که شاید در نگاه اول مرتبط به نظر نرسد، پیوند دهیم.

درباره این ایده بحث کنید

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

به محض باز شدن رشتهٔ بحث، تیم BeeWare و سایر اعضای جامعه پاسخ خواهند داد. تیم اصلی تلاش خواهد کرد تا ظرف دو روز کاری حداقل یک برداشت اولیه از ایدهٔ شما ارائه دهد. اگر ایده‌ای به‌ویژه پیچیده باشد، تحلیل دقیق‌تر ممکن است تا یک هفته طول بکشد. رویدادهایی مانند تعطیلات و کنفرانس‌ها ممکن است این بازه‌های زمانی را کمی طولانی‌تر کنند.

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

مهم است بدانید که همه ایده‌ها پذیرفته نخواهند شد. دلیل اینکه این فرایند با یک پیشنهاد شروع می‌شود این است که شما تمام کار را انجام ندهید و بعداً متوجه شوید دلیلی وجود دارد که تغییر شما پذیرفته نمی‌شود.

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

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

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

تبدیل به یک درخواست رسمی ویژگی

وقتی بحث به اجماع دربارهٔ شکل یک قابلیت رسید، می‌توانید در ردیاب مسئلهٔ beeware یک مسئلهٔ درخواست قابلیت جدید ایجاد کنید که خلاصه‌ای از بحث را ارائه دهد و برای زمینه به آن ارجاع دهد.

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

راه‌اندازی محیط توسعه

مشارکت در BeeWare مستلزم راه‌اندازی یک محیط توسعه است.

پیش‌نیازها

شما باید پیش‌نیازهای زیر را نصب کنید.

BeeWare به پایتون 3.10+ نیاز دارد. همچنین به روشی برای مدیریت محیط‌های مجازی (مانند venv) نیاز خواهید داشت.

می‌توانید با اجرای دستور زیر، نسخهٔ پایتونی را که نصب کرده‌اید بررسی کنید:

$ python3 --version

اگر بیش از یک نسخه از پایتون نصب کرده باشید، ممکن است لازم باشد python3 را با شماره نسخهٔ مشخصی جایگزین کنید (مثلاً python3.13)

ما توصیه می‌کنیم از نسخه‌های تازه منتشرشدهٔ پایتون (یعنی نسخه‌هایی که شمارهٔ نسخهٔ خرد «.0» یا «.1» دارند، مانند 3.14.0) خودداری کنید. دلیل آن این است که ابزارهای لازم برای پشتیبانی از پایتون در macOS اغلب با تأخیر عرضه می‌شوند و معمولاً برای نسخه‌های پایدار تازه‌منتشرشدهٔ پایتون در دسترس نیستند.

BeeWare به پایتون 3.10+ نیاز دارد. همچنین به روشی برای مدیریت محیط‌های مجازی (مانند venv) نیاز خواهید داشت.

می‌توانید با اجرای دستور زیر، نسخهٔ پایتونی را که نصب کرده‌اید بررسی کنید:

$ python3 --version

اگر بیش از یک نسخه از پایتون نصب کرده باشید، ممکن است لازم باشد python3 را با شماره نسخهٔ مشخصی جایگزین کنید (مثلاً python3.13)

ما توصیه می‌کنیم از نسخه‌های تازه منتشرشدهٔ پایتون (یعنی نسخه‌هایی که شمارهٔ نسخهٔ خرد «.0» یا «.1» دارند، مانند 3.14.0) خودداری کنید. دلیل آن این است که ابزارهای لازم برای پشتیبانی از پایتون روی لینوکس اغلب با تأخیر عرضه می‌شوند و معمولاً برای نسخه‌های پایدار تازه‌منتشرشدهٔ پایتون در دسترس نیستند.

BeeWare به پایتون 3.10+ نیاز دارد. همچنین به روشی برای مدیریت محیط‌های مجازی (مانند venv) نیاز خواهید داشت.

می‌توانید با اجرای دستور زیر، نسخهٔ پایتونی را که نصب کرده‌اید بررسی کنید:

C:\...>py -3 --version

اگر بیش از یک نسخه از پایتون نصب کرده باشید، ممکن است لازم باشد -3 را با شماره نسخهٔ مشخصی جایگزین کنید (مثلاً -python3.13)

ما توصیه می‌کنیم از نسخه‌های تازه منتشرشدهٔ پایتون (یعنی نسخه‌هایی که شمارهٔ نسخهٔ خرد «.0» یا «.1» دارند، مانند 3.14.0) خودداری کنید. دلیل آن این است که ابزارهای لازم برای پشتیبانی از پایتون روی ویندوز اغلب با تأخیر عرضه می‌شوند و معمولاً برای نسخه‌های پایدار تازه‌منتشرشدهٔ پایتون در دسترس نیستند.

محیط توسعه خود را راه‌اندازی کنید

روش پیشنهادی برای راه‌اندازی محیط توسعهٔ شما برای BeeWare استفاده از یک محیط مجازی است و سپس نصب نسخهٔ توسعهٔ BeeWare و وابستگی‌های آن.

مخزن BeeWare را کلون کنید

سپس به صفحه BeeWare در گیت‌هاب، بروید و اگر قبلاً این کار را نکرده‌اید، مخزن را فورک کنید به حساب کاربری خود. سپس، روی دکمه «<> Code» در فورک خود کلیک کنید. اگر برنامه دسکتاپ گیت‌هاب را روی رایانه خود نصب دارید، می‌توانید «Open with GitHub Desktop» را انتخاب کنید؛ در غیر این صورت، URL HTTPS ارائه‌شده را کپی کرده و از آن برای کلون کردن مخزن روی رایانه خود با استفاده از خط فرمان استفاده کنید:

مخزن BeeWare را فورک کنید، و سپس:

$ git clone https://github.com/<your username>/beeware.git

(نام کاربری گیت‌هاب خود را جایگزین کنید)

مخزن BeeWare را فورک کنید، و سپس:

$ git clone https://github.com/<your username>/beeware.git

(نام کاربری گیت‌هاب خود را جایگزین کنید)

مخزن BeeWare را فورک کنید، و سپس:

C:\...>git clone https://github.com/<your username>/beeware.git

(نام کاربری گیت‌هاب خود را جایگزین کنید)

یک محیط مجازی ایجاد کنید

برای راه‌اندازی یک محیط مجازی و ارتقا pip، اجرا کنید:

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

دستور شما اکنون باید یک پیش‌وند (.venv) در جلوی آن داشته باشد.

نصب کنید

حالا که کد منبع را در اختیار دارید، می‌توانید یک نصب قابل ویرایش از (https://setuptools.pypa.io/en/latest/userguide/development_mode.html) را در محیط توسعه خود انجام دهید. دستور زیر را اجرا کنید:

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

پیش‌تأیید را فعال کنید

BeeWare از ابزاری به نام pre-commit برای شناسایی مشکلات ساده و استانداردسازی قالب‌بندی کد استفاده می‌کند. این کار با نصب یک گیت هوک انجام می‌شود که پیش از نهایی‌سازی هر commit گیت، به‌طور خودکار مجموعه‌ای از لینترهای کد را اجرا می‌کند. برای فعال‌سازی pre-commit، دستور زیر را اجرا کنید:

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

اکنون شما آماده‌اید تا روی BeeWare هک کردن را شروع کنید!

کار از شعبه

قبل از اینکه روی تغییارتان کار را شروع کنید، مطمئن شوید که یک شاخه ایجاد کرده‌اید. به‌طور پیش‌فرض، وقتی فورک مخزن خود را کلون می‌کنید، روی شاخهٔ main چک‌اوت می‌شوید. این یک کپی مستقیم از شاخهٔ BeeWare در main است.

در حالی که می‌توانید از شاخهٔ main خود درخواست کشش ارسال کنید، ترجیح داده می‌شود این کار را انجام ندهید. اگر درخواستی ارسال کنید که تقریباً درست باشد، عضو تیم اصلی که درخواست شما را بررسی می‌کند ممکن است بتواند تغییرات لازم را اعمال کند، به‌جای اینکه بازخورد دهد و درخواست یک تغییر جزئی کند. با این حال، اگر درخواست کشش خود را از شاخهٔ main ارسال کنید، بازبینان از انجام اصلاحات منع می‌شوند.

کار کردن روی شاخهٔ اصلی شما نیز پس از تکمیل اولین درخواست کشیدن برایتان دشوار می‌شود. اگر بخواهید روی دومین درخواست کشیدن کار کنید، به یک نسخهٔ «تمیز» از شاخهٔ اصلی پروژهٔ بالادست نیاز دارید تا دومین مشارکت خود را بر اساس آن انجام دهید؛ اگر اولین مشارکت خود را از شاخهٔ main انجام داده باشید، دیگر آن نسخهٔ تمیز در دسترس شما نخواهد بود.

در عوض، شما باید تغییرات خود را در یک شعبهٔ ویژگی ایجاد کنید. یک شعبهٔ ویژگی نام ساده‌ای دارد تا تغییری را که ایجاد کرده‌اید شناسایی کند. برای مثال، اگر در حال رفع باگی هستید که باعث مشکلات ساخت (build) در ویندوز ۱۱ می‌شود، ممکن است یک شاخهٔ ویژگی به نام fix-win11-build ایجاد کنید. اگر باگ شما به یک مشکل خاص که گزارش شده است مربوط می‌شود، همچنین رایج است که شمارهٔ آن مشکل را در نام شاخه ذکر کنید (مثلاً fix-1234).

برای ایجاد یک شاخهٔ ویژگی fix-win11-build، اجرا کنید:

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build
از گسترش دامنه پروژه جلوگیری کنید

«افزایش تدریجی دامنه» زمانی رخ می‌دهد که فهرست مشکلاتی که با یک مشارکت حل شده‌اند یا ویژگی‌هایی که پیاده‌سازی شده‌اند، به‌طور قابل‌توجهی فراتر از آنچه در آغاز کار در نظر گرفته شده بود، رشد کند. شما با یک مسئله ساده شروع می‌کنید؛ یک مشکل مرتبط را کشف می‌کنید و تصمیم می‌گیرید آن را هم اصلاح کنید؛ سپس مسئله‌ای سوم… قبل از آنکه متوجه شوید، یک درخواست کشش دارید که پنج مسئله را بسته و سه ویژگی جدید اضافه کرده و شامل ده‌ها فایل است.

گسترش دامنه پروژه برای همه پیش می‌آید. این مفهومی است که برای توسعه‌دهندگان باتجربه کاملاً آشناست؛ همه ما بارها آن را تجربه کرده‌ایم و با تمام مشکلاتی که به همراه دارد روبه‌رو شده‌ایم.

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

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

توسعه نرم‌افزار همیشه فرآیندی از بهبود تدریجی است. هر مشارکت فردی باید پس از ادغام، پایگاه کد را در وضعیتی بهتر قرار دهد، اما کاملاً قابل قبول است که باگ‌ها یا بخش‌هایی از ویژگی‌ها را به‌عنوان کار برای بهبودهای آینده باقی بگذاریم. این ممکن است به معنای تقسیم یک درخواست برداشت (pull request) به چند بخش مستقل برای بازبینی جداگانه باشد، یا ثبت یک مسئله تا شخص دیگری بتواند آن را بررسی و حل کند.

محدود کردن دامنه هر مشارکت به همه افراد درگیر، از جمله خودتان، کمک می‌کند. بازبینان شما و حتی خودتان از آن قدردانی خواهید کرد.

مستندسازی ساختمان

قبل از انجام هرگونه تغییری در مستندات BeeWare، مفید است که تأیید کنید می‌توانید مستندات موجود را بسازید.

شما باید یک تفسیرگر Python 3.13 را نصب و در مسیر خود در دسترس داشته باشید (یعنی python3.13 باید یک تفسیرگر Python 3.13 را راه‌اندازی کند).

BeeWare از tox برای تولید مستندات استفاده می‌کند. دستورات زیر باید از همان محل فایل tox اجرا شوند که در دایرکتوری ریشه پروژه قرار دارد.

پیش‌نمایش مستندات زنده

برای پشتیبانی از ویرایش سریع مستندات، BeeWare دارای حالت «پیش‌نمایش زنده» است.

پیش‌نمایش زنده با هشدارها ساخته خواهد شد!

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

یک WARNING با یک ERROR متفاوت است. اگر مسئله‌ای را معرفی کنید که به‌عنوان یک ERROR در نظر گرفته شود، سرویس زنده شکست خواهد خورد و نیاز به راه‌اندازی مجدد دارد. تا زمانی که مسئله WARNING حل نشود، دوباره راه‌اندازی نخواهد شد.

برای راه‌اندازی سرور زنده:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

این کار مستندات را ایجاد می‌کند، یک سرور وب راه‌اندازی می‌کند تا مستندات را ارائه دهد و سیستم فایل را برای هرگونه تغییر در منبع مستندات زیر نظر می‌گیرد.

پس از راه‌اندازی سرور، چیزی شبیه به موارد زیر را در خروجی کنسول مشاهده خواهید کرد:

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

یک مرورگر باز کنید و به آدرس URL ارائه‌شده بروید. اکنون می‌توانید روی مستندات تکرار کنید. اگر تغییری شناسایی شود، مستندات بازسازی خواهد شد و هر مرورگری که صفحهٔ تغییرشده را مشاهده می‌کند، به‌طور خودکار تازه‌سازی خواهد شد.

docs-live یک گام اولیه است.

اجرای docs-live برای کار با سرور زنده جهت تکرارهای اولیه در نظر گرفته شده است. شما باید همیشه قبل از ارسال درخواست کش یک ساخت محلی اجرا کنید.

ساخت محلی

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

ایجاد یک بیلد محلی

برای ایجاد یک ساخت محلی:

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

خروجی این ساخت در دایرکتوری _build در ریشه پروژه قرار خواهد گرفت.

تولید یک بیلد محلی ترجمه‌شده

مستندات BeeWare به چندین زبان ترجمه شده است. به‌روزرسانی‌های مستندات انگلیسی ممکن است در نسخه‌های زبان‌های دیگر مشکل ایجاد کند. مهم است که قبل از ارسال درخواست کش، از کارکرد همه نسخه‌ها اطمینان حاصل کنید.

برای تولید یک نسخه از تمام ترجمه‌های موجود:

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

خروجی هر کامپایل زبان در دایرکتوری مربوطه با نام _build/html/<languagecode> قرار می‌گیرد، که <languagecode> کد دو یا پنج‌نقطه‌ای زبان موردنظر است (مثلاً برای فرانسوی fr، برای ایتالیایی it و غیره).

اگر در یک ساخت مشکل پیدا کنید، می‌توانید آن ساخت را به‌طور جداگانه با اجرای tox -e docs-<languagecode> اجرا کنید. برای مثال، برای ساخت تنها مستندات فرانسوی، اجرا کنید:

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

خروجی یک ساخت تک‌زبانه در دایرکتوری _build خواهد بود.

لینت‌گذاری مستندات

فرآیند ساخت مشکلات مارک‌داون را شناسایی می‌کند، اما BeeWare بررسی‌های اضافی بیشتری برای سبک و قالب‌بندی انجام می‌دهد که به آن «لینتینگ» گفته می‌شود. برای اجرای بررسی‌های لینت:

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

این تأیید می‌کند که مستندات حاوی موارد زیر نیست:

  • لینک‌های مرده
  • کلمات اشتباه املایی

اگر املای صحیح یک کلمه به‌عنوان اشتباه شناسایی شود، آن کلمه را در لیست داخل docs/spelling_wordlist اضافه کنید. این کار کلمه را به فرهنگ لغت SpellChecker اضافه می‌کند. هنگام افزودن به این لیست، به خاطر داشته باشید:

  • ما املای آمریکایی را ترجیح می‌دهیم، با برخی آزادی‌ها برای اصطلاحات محاوره‌ای خاص برنامه‌نویسی (مثلاً «apps») و فعل‌انگاری اسامی (مثلاً «scrollable»).
  • هر ارجاع به نام یک محصول باید از شیوهٔ نگارش بزرگ‌نویسی ترجیحی آن محصول استفاده کند. (مثلاً «macOS»، «GTK»، «pytest»، «Pygame»، «PyScript»)
  • اگر یک واژه به‌عنوان «کد» استفاده می‌شود، باید به‌صورت یک عبارت بستی (like this) نقل شود، نه اینکه به فرهنگ لغت اضافه شود.
نوشتن مستندات

این‌ها گام‌هایی هستند که باید برای نوشتن مشارکت مستندسازی خود در BeeWare دنبال کنید.

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

اگر در حال ویرایش مستندات موجود هستید، باید فایل را در دایرکتوری /docs/en پیدا کنید. ساختار فایل‌ها مطابق ساختار صفحات است، بنابراین می‌توانید با استفاده از URL مستندات، فایل را بیابید.

افزودن مستندات جدید

اگر در حال افزودن یک سند جدید هستید، چند مرحلهٔ دیگر نیز وجود دارد.

شما باید سند را در مکان مناسب درون دایرکتوری docs/en ایجاد کنید. برای بحث، فرض می‌کنیم شما یک سند جدید با نام فایل new_doc.md اضافه می‌کنید.

سپس باید فایل docs/en/SUMMARY.md را به‌روزرسانی کنید تا فایل جدیدتان را شامل شود. SUMMARY.md اساساً برای بازتاب ساختار دایرکتوری docs/en سازمان‌دهی شده است، اما مهم‌تر از آن، ساختار نوار کناری سمت چپ را به‌طور مستقیم تعیین می‌کند. اگر بخشی را که قصد دارید new_doc.md را در آن درج کنید پیدا کنید و یک مسیر وایلدکارد را مشاهده کنید، نیازی نیست در SUMMARY.md هیچ تغییری ایجاد کنید. برای مثال:

- ./path/to/directory/*

اگر بخشی که قصد دارید new_doc.md را در آن قرار دهید شامل فهرستی از لینک‌های جداگانه مارک‌داون باشد، باید یک لینک صریح به لینک خود اضافه کنید. برای مثال:

- [My new document](new_doc.md)

نوشتن مستندات شما

اکنون می‌توانید فایل مورد نظر را در ویرایشگر خود باز کرده و شروع به نوشتن کنید.

ما یک راهنمای سبک مستندسازی داریم که دستورالعمل‌های ما را برای نوشتن مستندسازی BeeWare تشریح می‌کند.

اضافه کردن یادداشت تغییر

بسیاری از ابزارهای BeeWare از towncrier برای کمک به ساخت یادداشت‌های انتشار هر نسخه استفاده می‌کنند. وقتی یک درخواست کشش (pull request) را به یکی از ابزارهای مربوطه ارسال می‌کنید، باید شامل یک یادداشت تغییر باشد – این یادداشت تغییر تبدیل به مدخلی در یادداشت‌های انتشار می‌شود که تغییر انجام‌شده را توصیف می‌کند.

هر درخواست کشش باید حداقل یک فایل در دایرکتوری changes/ داشته باشد که توضیح کوتاهی از تغییری که توسط درخواست کشش پیاده‌سازی شده ارائه دهد. یادداشت تغییر باید به فرمت مارک‌داون باشد، در فایلی با نامی به شکل <id>.<fragment type>.md. اگر تغییری که پیشنهاد می‌دهید یک باگ را رفع می‌کند یا ویژگی‌ای را پیاده‌سازی می‌کند که برای آن شماره ایزیس (issue) موجود است، شناسه همان شماره تیکت خواهد بود. اگر تغییر مربوط به هیچ ایرادی نباشد، شماره PR می‌تواند به‌عنوان شناسه استفاده شود. شما تا قبل از ارسال درخواست کشش این شماره را نخواهید دانست، بنابراین اولین مرحله CI در بررسی towncrier شکست خواهد خورد؛ یادداشت تغییر را اضافه کرده و یک به‌روزرسانی PR ارسال کنید تا CI با موفقیت عبور کند.

پنج نوع قطعه وجود دارد:

  • feature: PR یک رفتار یا قابلیت جدید را اضافه می‌کند که قبلاً امکان‌پذیر نبود (مثلاً افزودن پشتیبانی از یک قالب بسته‌بندی جدید، یا یک ویژگی جدید در یک قالب بسته‌بندی موجود)؛
  • bugfix: این PR یک باگ در پیاده‌سازی موجود را رفع می‌کند؛
  • doc: PR یک بهبود قابل توجه در مستندات است؛
  • removal; PR نمایانگر یک تغییر ناسازگار رو به عقب در رابط برنامه‌نویسی کاربردی BeeWare است؛ یا
  • misc; یک تغییر جزئی یا اداری (مثلاً اصلاح یک اشتباه تایپی، یک توضیح زبانی جزئی، یا به‌روزرسانی نسخهٔ یک وابستگی) که نیازی به اعلام در یادداشت‌های انتشار ندارد.

این توضیح در یادداشت تغییر باید یک خلاصه سطح بالا و «بازاریابی» از تغییر از دیدگاه کاربر باشد، نه یک توضیح فنی عمیق یا جزئیات پیاده‌سازی. این با پیام commit متفاوت است – پیام commit شرح می‌دهد چه کاری انجام شده تا توسعه‌دهندگان آینده بتوانند دلیل تغییر را دنبال کنند؛ یادداشت تغییر توصیفی است برای بهره‌مندی کاربران که ممکن است از ساختار داخلی اطلاع نداشته باشند.

برای مثال، اگر شما یک باگ مربوط به نام‌گذاری پروژه را رفع کنید، پیام کامیت ممکن است چنین باشد:

یک بررسی عبارت منظم قوی‌تر اعمال کنید تا نام‌های پروژه‌هایی که با اعداد شروع می‌شوند، مجاز نباشند.

یادداشت تغییر مربوطه چیزی شبیه به این خواهد بود:

نام پروژه‌ها دیگر نمی‌توانند با عدد شروع شوند.

برخی PRها ممکن است چندین ویژگی را معرفی کنند و چندین باگ را رفع نمایند، یا چندین تغییر ناسازگار رو به عقب را اعمال کنند. در این صورت، PR ممکن است چندین فایل یادداشت تغییر داشته باشد. اگر نیاز باشد دو نوع قطعه را با یک شناسه یکسان مرتبط کنید، می‌توانید یک پسوند عددی اضافه کنید. برای مثال، اگر PR 789 ویژگی‌ای را که در تیکت 123 توصیف شده بود اضافه کرده، باگی را که در تیکت 234 توصیف شده بود بسته و همچنین دو تغییر ناسازگار رو به عقب ایجاد کرده باشد، ممکن است 4 فایل یادداشت تغییر داشته باشید:

  • 123.feature.md
  • 234.bugfix.md
  • 789.removal.1.md
  • 789.removal.2.md

برای اطلاعات بیشتر درباره towncrier و انواع فرگمنت‌ها به News Fragments مراجعه کنید. همچنین می‌توانید نمونه‌های موجود فرگمنت‌های خبری را در دایرکتوری changes از مخزن BeeWare مشاهده کنید. اگر این پوشه خالی باشد، احتمالاً به این دلیل است که BeeWare به‌تازگی یک نسخهٔ جدید منتشر کرده است؛ فایل‌های یادداشت تغییرات با هر نسخه حذف و ترکیب می‌شوند تا یادداشت‌های نسخه به‌روزرسانی شوند. می‌توانید آن فایل را ببینید تا با سبک کامنت مورد نیاز آشنا شوید؛ همچنین می‌توانید به PRهای اخیراً ادغام‌شده مراجعه کنید تا نحوه قالب‌بندی یادداشت‌های تغییرات خود را مشاهده کنید.

ارسال درخواست ادغام

حالا که تمام تغییرات‌تان را کامیت کرده‌اید، آماده‌اید تا یک درخواست کش ارسال کنید. برای اینکه فرایند بازبینی به‌خوبی پیش برود، چند مرحله وجود دارد که باید انجام دهید.

کار با پیش‌تعهد

هرگاه شما هر تغییری را commit کنید، pre-commit به‌طور خودکار اجرا می‌شود. اگر در commit مشکلی یافت شود، این امر باعث شکست commit شما خواهد شد. در صورت امکان، pre-commit تغییرات لازم را برای اصلاح مشکلات یافته‌شده اعمال می‌کند. در مثال زیر، یک مشکل در قالب‌بندی کد توسط بررسی ruff یافت شده است:

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

در این مورد، ruff به‌طور خودکار مشکل را برطرف کرد؛ بنابراین می‌توانید هر فایلی را که در نتیجه بررسی‌های پیش از commit تغییر کرده بود دوباره اضافه کرده و تغییر را مجدداً commit کنید. با این حال، برخی بررسی‌ها نیاز به اعمال تغییرات دستی دارند. پس از انجام آن تغییرات، هر فایل تغییر یافته را دوباره اضافه کرده و commit کنید.

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

وقتی همه چیز با موفقیت انجام شود، پیامی خواهید دید که نشان می‌دهد کامیت نهایی شده است و با اجرای git log، کامیت شما به‌عنوان جدیدترین افزوده نمایش داده می‌شود. اکنون آماده‌اید تا تغییرات را به گیت‌هاب پوش کنید.

تغییرات خود را به گیت‌هاب ارسال کنید و درخواست برداشتن (pull request) خود را ایجاد کنید.

اولین باری که به گیت‌هاب ارسال می‌کنید، یک URL به شما ارائه می‌شود که شما را مستقیماً به صفحه گیت‌هاب برای ایجاد یک درخواست کشش جدید هدایت می‌کند. آن URL را دنبال کرده و درخواست کشش خود را ایجاد کنید.

مثال زیر نشان می‌دهد که در push چه انتظاری باید داشت، با URL برجسته شده.

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

اگر قبلاً شاخهٔ جاری را به گیت‌هاب ارسال کرده‌اید، دیگر این URL را دریافت نخواهید کرد. با این حال، راه‌های دیگری برای دسترسی به URL ایجاد PR وجود دارد:

  • به مخزن بالادست بروید، روی «درخواست‌های کشیدن» کلیک کنید، سپس «درخواست کشیدن جدید» را انتخاب کرده و شاخه‌ای را که می‌خواهید درخواست خود را از آن ارسال کنید، برگزینید.
  • اگر اخیراً پُش کرده‌اید، به مخزن بالادست بروید، بنری را که بالای فهرست فایل‌ها نشان می‌دهد مخزن «پُش‌های اخیر داشته است» پیدا کنید و روی دکمه «مقایسه و درخواست کشیدن» کلیک کنید.
  • از دستور gh pr create در CLI گیت‌هاب استفاده کنید و پاسخ‌های لازم را وارد کنید.
  • از دستور gh pr create --web در GitHub CLI استفاده کنید تا مرورگر وب به صفحهٔ ایجاد PR باز شود.

هر یک از این گزینه‌ها به شما امکان می‌دهد تا درخواست برداشت جدید خود را ایجاد کنید.

CLI گیت‌هاب: gh

GitHub ابزار GitHub CLI را ارائه می‌دهد که از طریق دستور gh به شما امکان دسترسی به بسیاری از قابلیت‌های GitHub را از طریق ترمینال می‌دهد. مستندات GitHub CLI تمام قابلیت‌ها را پوشش می‌دهد.

محتوای درخواست کشش

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

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

اگر هر مورد بازتولید یا هر پروتکل آزمایشی که استفاده کرده‌اید و هنوز جزئی از تغییرات موجود در PR نیست، باید توضیح داده شده و در PR گنجانده شود. توضیح باید شامل نحوه اجرای آن‌ها و اقداماتی باشد که برای بازتولید نتیجه مورد نظر باید انجام داد.

اگر درخواست برداشت شما مشکل شمارهٔ ۱۲۳۴ را حل می‌کند، باید عبارت Fixes #1234 را در توضیحات درخواست برداشت خود درج کنید. این کار باعث می‌شود که وقتی درخواست برداشت ادغام شود، مشکل به‌طور خودکار بسته شود. می‌توانید با استفاده از همان سینتکس #1234 به بحث‌ها، مشکلات یا درخواست‌های برداشت دیگر ارجاع دهید. برای ارجاع به مشکلی در مخزن دیگر، کافی است عدد را با علامت منفی (-) پیش‌وند کنید؛ برای مثال، python/cpython#1234 به مشکل شمارهٔ ۱۲۳۴ در مخزن CPython اشاره می‌کند.

ادغام مستمر

ادغام مداوم، یا CI، فرآیندی است برای اجرای بررسی‌های خودکار روی درخواست برداشت (pull request) شما. این کار می‌تواند شامل بررسی‌های ساده‌ای مانند اطمینان از قالب‌بندی صحیح کد باشد؛ اما شامل اجرای مجموعه تست‌ها و ساخت مستندات نیز می‌شود.

تغییرات متعددی وجود دارد که می‌تواند منجر به شکست CI شود. به‌طور کلی، ما PRهایی را که CI را پاس نمی‌کنند، بررسی نمی‌کنیم. اگر یک pull request بسازید و CI شکست بخورد، تا زمانی که CI پاس نشود، بررسی شما را آغاز نخواهیم کرد. اگر تغییرات شما منجر به شکست شود، مسئولیت شماست که علت را بررسی کرده و مشکل را برطرف کنید.

وقتی CI شکست می‌خورد، لینک‌های شکست در پایین صفحه PR، زیر عنوان «برخی از بررسی‌ها با موفقیت انجام نشدند» نمایش داده می‌شوند. شما فهرستی از چک‌های ناموفق را خواهید دید که در صورت وجود چک‌های موفق نیز در بالای فهرست تمام چک‌ها نمایش داده می‌شود. اگر روی لینک خطا کلیک کنید، به لاگ هدایت می‌شوید. لاگ اغلب تمام اطلاعات لازم برای پی بردن به علت خطا را در اختیار شما قرار می‌دهد. لاگ را مطالعه کنید و سعی کنید بفهمید چرا خطا رخ می‌دهد، سپس برای رفع آن اقدام لازم را انجام دهید.

گاهی اوقات بررسی CI به‌دلیل دلایلی که ارتباطی با تغییرات شما ندارد، ناموفق می‌شود. این ممکن است به‌خاطر مشکلی در ماشینی باشد که بررسی CI را اجرا می‌کند یا به‌دلیل ناپایداری خودِ بررسی CI. اگر با خطا مواجه شدید و مطمئن هستید که ارتباطی با تغییرات شما ندارد، در PR خود توضیحی در این مورد اضافه کنید تا ما بررسی کنیم.

برای راه‌اندازی یک اجرای جدید CI، باید تغییرات جدید را به شاخه‌ی خود پُش کنید.

اگر در موقعیتی قرار گرفتید که برای تأیید CI به کمک نیاز دارید، در PR یک کامنت بگذارید و ما را در جریان بگذارید تا هر چه در توان داریم برای کمک به شما انجام دهیم.

بررسی‌های pre-commit و towncrier

اگر هر یک از بررسی‌های pre-commit یا towncrier با شکست مواجه شود، مانع اجرای بیشتر بررسی‌های CI خواهد شد. قبل از اینکه مجموعه کامل بررسی‌ها اجرا شود، باید مشکلات مربوطه را برطرف کنید.

ما منابع CI محدودی داریم. مهم است بدانید که هر بار که به شاخه push می‌کنید، CI آغاز می‌شود. اگر قصد دارید چندین تغییر انجام دهید، بهتر است آن‌ها را به‌صورت محلی اعمال کرده و همه را یک‌جا push کنید. CI تنها روی جدیدترین commit در هر مجموعه اجرا می‌شود و بدین ترتیب بار سیستم CI ما به حداقل می‌رسد.

فرآیند ارسال PR شما تا زمانی که CI را پاس نکند یا نتوانید توضیح دهید چرا پاس نشده است، کامل نمی‌شود.