ارسال یک درخواست تغییر¶
حالا که تمام تغییراتتان را کامیت کردهاید، آمادهاید تا یک درخواست کش ارسال کنید. برای اینکه فرایند بازبینی بهخوبی پیش برود، چند مرحله وجود دارد که باید انجام دهید.
کار با پیشتعهد¶
هرگاه شما هر تغییری را 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 را پاس نکند یا نتوانید توضیح دهید چرا پاس نشده است، کامل نمیشود.
پُلریکوست شما ممکن است پیش از آنکه بتواند بازبینی شود، به محتوای اضافی مانند یادداشت تغییر نیاز داشته باشد.