Chapters ▾ 2nd Edition

6.2 GitHub (گیت هاب) - مشارکت در یک پروژه (Contributing to a Project)

مشارکت در یک پروژه (Contributing to a Project)

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

فورک کردن پروژه‌ها (Forking Projects)

اگر می‌خواهید در پروژه‌ای موجود مشارکت کنید که دسترسی ارسال (push) به آن را ندارید، می‌توانید پروژه را «fork» کنید. وقتی پروژه‌ای را «fork» می‌کنید، گیت‌هاب یک نسخه کپی از پروژه ایجاد می‌کند که کاملاً متعلق به شماست؛ این نسخه در فضای نام شما قرار دارد و می‌توانید به آن ارسال (push) انجام دهید.

یادداشت

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

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

برای فورک کردن پروژه، به صفحه پروژه مراجعه کرده و روی دکمه «Fork» در بالای سمت راست صفحه کلیک کنید.

The “Fork” button
نمودار 88. The “Fork” button

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

روند کاری گیت‌هاب (The GitHub Flow)

گیت‌هاب حول یک روند همکاری خاص طراحی شده است که مرکز آن Pull Requestها هستند. این روند چه در همکاری با تیمی کوچک در یک مخزن مشترک و چه در شرکتی جهانی یا شبکه‌ای از افراد ناشناس که از طریق ده‌ها فورک به پروژه‌ای مشارکت می‌کنند، کارآمد است. مرکز این روند، روش شاخه‌های موضوعی (Topic Branches) است که در انشعاب‌گیری در گیت (Git Branching) شرح داده شده است.

روند کار معمولاً به این صورت است:

  1. پروژه را فورک کنید.

  2. شاخه موضوعی (topic branch) از شاخه master بسازید.

  3. چند کامیت برای بهبود پروژه انجام دهید.

  4. این شاخه را به پروژه گیت‌هاب خود ارسال کنید.

  5. یک Pull Request روی گیت‌هاب باز کنید.

  6. در مورد آن بحث کنید و در صورت نیاز به ارسال کامیت‌های بیشتر ادامه دهید.

  7. مالک پروژه Pull Request را ادغام یا ببندد.

  8. شاخه master به‌روزشده را به فورک خود سینک کنید.

این اساساً همان روند کاری Integration Manager است که در جریان کاری مدیر ادغام (Integration-Manager Workflow) توضیح داده شده، با این تفاوت که به جای استفاده از ایمیل برای ارتباط و بررسی تغییرات، تیم‌ها از ابزارهای وب‌محور گیت‌هاب استفاده می‌کنند.

بیایید یک مثال از پیشنهاد تغییر در یک پروژه متن‌باز میزبانی شده روی گیت‌هاب را با استفاده از این روند بررسی کنیم.

نکته

به جای استفاده از رابط وب گیت‌هاب، می‌توانید از ابزار رسمی GitHub CLI نیز استفاده کنید. این ابزار روی ویندوز، مک‌او‌اس و لینوکس قابل استفاده است. برای دستورالعمل نصب و راهنمای استفاده به https://cli.github.com/ مراجعه کنید.

ایجاد یک Pull Request (Creating a Pull Request)

تونی به دنبال کدی برای اجرای روی میکروکنترلر برنامه‌پذیر Arduino خود است و برنامه بسیار خوبی در گیت‌هاب به آدرس https://github.com/schacon/blink پیدا کرده است.

The project we want to contribute to
نمودار 89. The project we want to contribute to

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

ابتدا، همانطور که پیش‌تر گفته شد، روی دکمه «Fork» کلیک می‌کنیم تا نسخه خودمان از پروژه را داشته باشیم. نام کاربری ما در اینجا «tonychacon» است، پس نسخه ما از این پروژه در آدرس https://github.com/tonychacon/blink قرار دارد و می‌توانیم آن را ویرایش کنیم. ما آن را به صورت محلی کلون می‌کنیم، یک شاخه موضوعی می‌سازیم، تغییر در کد را انجام می‌دهیم و در نهایت آن را به گیت‌هاب ارسال می‌کنیم.

$ git clone https://github.com/tonychacon/blink (1)
Cloning into 'blink'...

$ cd blink
$ git checkout -b slow-blink (2)
Switched to a new branch 'slow-blink'

$ sed -i '' 's/1000/3000/' blink.ino (macOS) (3)
# If you're on a Linux system, do this instead:
# $ sed -i 's/1000/3000/' blink.ino (3)

$ git diff --word-diff (4)
diff --git a/blink.ino b/blink.ino
index 15b9911..a6cc5a5 100644
--- a/blink.ino
+++ b/blink.ino
@@ -18,7 +18,7 @@ void setup() {
// the loop routine runs over and over again forever:
void loop() {
  digitalWrite(led, HIGH);   // turn the LED on (HIGH is the voltage level)
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
  digitalWrite(led, LOW);    // turn the LED off by making the voltage LOW
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
}

$ git commit -a -m 'Change delay to 3 seconds' (5)
[slow-blink 5ca509d] Change delay to 3 seconds
 1 file changed, 2 insertions(+), 2 deletions(-)

$ git push origin slow-blink (6)
Username for 'https://github.com': tonychacon
Password for 'https://tonychacon@github.com':
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://github.com/tonychacon/blink
 * [new branch]      slow-blink -> slow-blink

  1. فورک پروژه را به صورت محلی کلون کنیم.

  2. یک شاخه موضوعی با نام توصیفی بسازیم.

  3. تغییر مورد نظر را در کد اعمال کنیم.

  4. مطمئن شویم که تغییر خوب است.

  5. تغییر را به شاخه موضوعی کامیت کنیم.

  6. شاخه موضوعی جدید را به فورک گیت‌هاب خود ارسال کنیم.

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

همچنین می‌توانید به صفحه «Branches» در آدرس https://github.com/<user>/<project>/branches بروید، شاخه خود را پیدا کنید و از آنجا Pull Request جدید باز کنید.

Pull Request button
نمودار 90. Pull Request button

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

همچنین فهرستی از کامیت‌های شاخه موضوعی را می‌بینیم که نسبت به شاخه master «جلوتر» هستند (در این مورد فقط یک کامیت) و یک diff یکپارچه از تمام تغییراتی که در صورت ادغام این شاخه توسط مالک پروژه اعمال خواهند شد.

Pull Request creation page
نمودار 91. Pull Request creation page

وقتی روی دکمه «Create pull request» در این صفحه کلیک می‌کنید، صاحب پروژه‌ای که آن را فورک کرده‌اید، اطلاع دریافت می‌کند که کسی تغییراتی را پیشنهاد داده است و به صفحه‌ای لینک می‌شود که تمام این اطلاعات را دارد.

یادداشت

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

تکرار روی یک درخواست کشش (Iterating on a Pull Request)

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

جایی که این گفتگو ممکن است در ایمیل انجام شود، در جریان کاری که در گیت توزیع‌شده (Distributed git) توضیح داده شده، در گیت‌هاب این تعامل به صورت آنلاین انجام می‌شود. صاحب پروژه می‌تواند تفاوت‌های یکپارچه شده (unified diff) را بررسی کرده و با کلیک روی هر خط، نظر خود را ثبت کند.

Comment on a specific line of code in a Pull Request
نمودار 92. Comment on a specific line of code in a Pull Request

وقتی نگهدارنده پروژه این نظر را ثبت کند، فردی که درخواست pull را باز کرده (و در واقع هر کسی که مخزن را دنبال می‌کند) یک اطلاعیه دریافت خواهد کرد. بعداً درباره تنظیمات سفارشی این اطلاعیه‌ها صحبت خواهیم کرد، اما اگر او اعلان‌های ایمیلی را فعال کرده باشد، تونی ایمیلی شبیه این دریافت می‌کند:

Comments sent as email notifications
نمودار 93. Comments sent as email notifications

هر کسی همچنین می‌تواند نظر کلی درباره درخواست pull بگذارد. در Pull Request discussion page مثالی می‌بینیم که صاحب پروژه هم روی یک خط کد نظر می‌دهد و سپس در بخش بحث نظر کلی می‌گذارد. می‌توانید ببینید که نظرات کد نیز در گفتگو وارد شده‌اند.

Pull Request discussion page
نمودار 94. Pull Request discussion page

حالا مشارکت‌کننده می‌تواند ببیند برای پذیرفته شدن تغییرش چه کاری باید انجام دهد. خوشبختانه این کار بسیار ساده است. جایی که در ایمیل ممکن است مجبور باشید سری تغییرات خود را بازنویسی و مجدداً ارسال کنید، در گیت‌هاب فقط کافی است دوباره روی شاخه موضوعی commit کرده و push کنید که به طور خودکار درخواست pull را به‌روزرسانی می‌کند. در Pull Request final نیز می‌توانید ببینید که نظر قدیمی روی کد در درخواست pull به‌روزرسانی شده جمع شده است، چون روی خطی گذاشته شده بود که بعداً تغییر کرده است.

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

Pull Request final
نمودار 95. Pull Request final

یک نکته جالب این است که اگر روی تب «Files Changed» این درخواست pull کلیک کنید، «unified diff» را مشاهده می‌کنید — یعنی تفاوت کلی که در صورت ادغام این شاخه موضوعی، به شاخه اصلی اضافه خواهد شد. به زبان git diff، این تقریباً همان نمایش خودکار git diff master…​<branch> برای شاخه‌ای است که این درخواست pull بر اساس آن است. برای اطلاعات بیشتر درباره این نوع diff به تشخیص تغییرات ایجاد شده (Determining What Is Introduced) مراجعه کنید.

موضوع دیگری که متوجه خواهید شد این است که گیت‌هاب بررسی می‌کند که آیا این درخواست pull به صورت تمیز قابل ادغام است یا نه و دکمه‌ای برای ادغام روی سرور به شما ارائه می‌دهد. این دکمه فقط زمانی نمایش داده می‌شود که شما دسترسی نوشتن به مخزن داشته باشید و ادغام ساده‌ای ممکن باشد. اگر روی آن کلیک کنید، گیت‌هاب یک ادغام «non-fast-forward» انجام می‌دهد، یعنی حتی اگر ادغام می‌توانست fast-forward باشد، باز هم یک commit ادغام ایجاد خواهد کرد.

اگر ترجیح می‌دهید، می‌توانید شاخه را به صورت محلی pull کرده و ادغام کنید. اگر این شاخه را در شاخه master ادغام کنید و به گیت‌هاب push کنید، درخواست pull به طور خودکار بسته خواهد شد.

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

یادداشت
Not Only Forks

مهم است بدانید که می‌توانید درخواست pull را بین دو شاخه در یک مخزن نیز باز کنید. اگر با کسی روی یک ویژگی کار می‌کنید و هر دو دسترسی نوشتن به پروژه دارید، می‌توانید شاخه موضوعی را به مخزن push کنید و روی آن درخواست pull به شاخه master همان پروژه باز کنید تا فرایند بازبینی کد و بحث شروع شود. نیازی به فورک کردن نیست.

درخواست‌های پیشرفته برای ادغام (Advanced Pull Requests)

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

درخواست‌های ادغام به عنوان پچ‌ها (Pull Requests as Patches)

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

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

برای مثال، اگر دوباره به Pull Request final نگاه کنید، متوجه می‌شوید که مشارکت‌کننده کامیت خود را ری‌بیس نکرده و درخواست ادغام جدیدی نفرستاده است. بلکه کامیت‌های جدیدی اضافه کرده و آن‌ها را به شاخه موجود پوش کرده است. بدین ترتیب اگر در آینده به این درخواست ادغام مراجعه کنید، می‌توانید به راحتی تمام زمینه‌ی تصمیم‌گیری‌ها را پیدا کنید. زدن دکمه «Merge» در سایت عمداً یک کامیت ادغام ایجاد می‌کند که به درخواست ادغام اشاره دارد تا در صورت نیاز به سادگی بتوان به گفتگوی اصلی بازگشت و آن را بررسی کرد.

به‌روز بودن با شاخه اصلی (Keeping up with Upstream)

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

Pull Request does not merge cleanly
نمودار 96. Pull Request does not merge cleanly

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

اگر چیزی شبیه به Pull Request does not merge cleanly دیدید، باید شاخه خود را اصلاح کنید تا به رنگ سبز در بیاید و نگهدارنده مجبور به انجام کار اضافی نشود.

برای این کار دو گزینه اصلی دارید. می‌توانید شاخه خود را روی شاخه هدف (معمولاً شاخه master مخزن فورک شده) ری‌بیس کنید یا شاخه هدف را در شاخه خود ادغام کنید.

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

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

برای مثال فرض کنید در مثال “tonychacon”، نویسنده اصلی تغییراتی داده که باعث ایجاد تعارض در درخواست ادغام می‌شود. مراحل زیر را طی می‌کنیم:

$ git remote add upstream https://github.com/schacon/blink (1)

$ git fetch upstream (2)
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (3/3), done.
Unpacking objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
From https://github.com/schacon/blink
 * [new branch]      master     -> upstream/master

$ git merge upstream/master (3)
Auto-merging blink.ino
CONFLICT (content): Merge conflict in blink.ino
Automatic merge failed; fix conflicts and then commit the result.

$ vim blink.ino (4)
$ git add blink.ino
$ git commit
[slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \
    into slower-blink

$ git push origin slow-blink (5)
Counting objects: 6, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 682 bytes | 0 bytes/s, done.
Total 6 (delta 2), reused 0 (delta 0)
To https://github.com/tonychacon/blink
   ef4725c..3c8d735  slower-blink -> slow-blink

  1. مخزن اصلی را به عنوان ریموتی به نام upstream اضافه کنید.

  2. جدیدترین تغییرات را از آن ریموت دریافت کنید.

  3. شاخه اصلی آن مخزن را در شاخه موضوعی خود ادغام کنید.

  4. تعارض پیش آمده را برطرف کنید.

  5. تغییرات را به همان شاخه موضوعی پوش کنید.

وقتی این کار را انجام دهید، درخواست ادغام به طور خودکار به‌روزرسانی شده و دوباره بررسی می‌شود تا ببیند آیا به‌طور تمیز ادغام می‌شود یا خیر.

Pull Request now merges cleanly
نمودار 97. Pull Request now merges cleanly

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

اگر واقعاً می‌خواهید شاخه را ری‌بیس کنید تا آن را تمیز کنید، قطعاً می‌توانید این کار را انجام دهید، اما اکیداً توصیه می‌شود که روی شاخه‌ای که درخواست ادغام روی آن باز است، پوش فورس انجام ندهید. اگر افراد دیگری آن را دریافت و روی آن کار کرده باشند، با مشکلات بسیار زیادی مواجه خواهید شد که در خطرات بازپایه‌گذاری (The Perils of Rebasing) توضیح داده شده است. در عوض، شاخه ری‌بیس شده را به شاخه جدیدی در گیت‌هاب پوش کنید و درخواست ادغام جدیدی باز کنید که به درخواست قبلی ارجاع دهد، سپس درخواست اصلی را ببندید.

ارجاع‌ها (References)

شاید سؤال بعدی شما این باشد: «چگونه به درخواست ادغام قدیمی ارجاع دهم؟» واقعیت این است که راه‌های بسیار زیادی برای ارجاع به چیزهای دیگر تقریباً در هر جایی که در گیت‌هاب می‌توانید بنویسید وجود دارد.

بیایید با نحوه ارجاع به درخواست ادغام یا مسئله‌ی دیگر شروع کنیم. تمام درخواست‌های ادغام و مسائل شماره‌گذاری شده و این شماره‌ها در پروژه یکتا هستند. برای مثال، نمی‌توانید درخواست ادغام شماره ۳ و مسئله شماره ۳ داشته باشید که هر دو در یک پروژه باشند. اگر بخواهید به هر درخواست ادغام یا مسئله‌ای از هر درخواست یا مسئله‌ی دیگر ارجاع دهید، کافی است <شماره> را در هر کامنت یا توضیحی بنویسید. همچنین می‌توانید دقیق‌تر باشید اگر مسئله یا درخواست ادغام در جای دیگری است؛ برای ارجاع به مسئله یا درخواست ادغام در فورکی از مخزنی که در آن هستید، username<شماره> را بنویسید، یا برای ارجاع به چیزی در مخزن دیگر، username/repo#<شماره> را استفاده کنید.

 بیایید یک مثال را بررسی کنیم.
فرض کنید در مثال قبلی، شاخه را بازبیس (rebase) کرده‌ایم، یک درخواست کشش (pull request) جدید برای آن ساخته‌ایم و حالا می‌خواهیم از درخواست کشش قدیمی در درخواست جدید ارجاع دهیم.
همچنین می‌خواهیم به یک مسئله (issue) در فورک مخزن و یک مسئله در پروژه‌ای کاملاً متفاوت اشاره کنیم.
می‌توانیم توضیحات را دقیقاً مانند <<_pr_references>> پر کنیم.
Cross references in a Pull Request
نمودار 98. Cross references in a Pull Request

وقتی این درخواست کشش را ارسال کنیم، همه این موارد به شکل Cross references rendered in a Pull Request نمایش داده می‌شوند.

Cross references rendered in a Pull Request
نمودار 99. Cross references rendered in a Pull Request

توجه کنید که URL کامل گیت‌هاب که وارد کرده‌ایم، به اطلاعات مورد نیاز خلاصه شده است.

حالا اگر تونی برگردد و درخواست کشش اصلی را ببندد، می‌بینیم که با اشاره به آن در درخواست جدید، گیت‌هاب به صورت خودکار یک رویداد پیگیری (trackback) در جدول زمانی درخواست کشش ایجاد کرده است. این بدان معناست که هر کسی که این درخواست کشش را مشاهده کند و ببیند که بسته شده، به راحتی می‌تواند به آن درخواست کشش که این را جایگزین کرده، لینک بزند. این لینک چیزی شبیه به Link back to the new Pull Request in the closed Pull Request timeline خواهد بود.

Link back to the new Pull Request in the closed Pull Request timeline
نمودار 100. Link back to the new Pull Request in the closed Pull Request timeline

علاوه بر شماره مسائل، می‌توانید به یک کامیت خاص با شناسه SHA-1 هم ارجاع دهید. باید یک SHA-1 کامل ۴۰ حرفی مشخص کنید، اما اگر گیت‌هاب آن را در یک کامنت ببیند، مستقیماً به کامیت لینک می‌دهد. دوباره، می‌توانید به کامیت‌ها در فورک‌ها یا مخازن دیگر به همان روشی که به مسائل اشاره می‌کنید، ارجاع دهید.

مارک‌داون با قابلیت‌های گیت‌هاب (GitHub Flavored Markdown)

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

برای نمونه‌ای از نحوه نوشتن و نمایش کامنت‌ها یا متن با استفاده از مارک‌داون، به An example of GitHub Flavored Markdown as written and as rendered مراجعه کنید.

An example of GitHub Flavored Markdown as written and as rendered
نمودار 101. An example of GitHub Flavored Markdown as written and as rendered

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

فهرست وظایف (Task Lists)

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

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

- [X] Write the code
- [ ] Write all the tests
- [ ] Document the code

اگر این را در توضیحات درخواست کشش یا مسئله بگنجانید، به شکل Task lists rendered in a Markdown comment نمایش داده می‌شود.

Task lists rendered in a Markdown comment
نمودار 102. Task lists rendered in a Markdown comment

این اغلب در درخواست‌های کشش استفاده می‌شود تا نشان دهد چه کارهایی باید روی شاخه انجام شود تا درخواست کشش آماده ادغام شود. قسمت جالب این است که می‌توانید صرفاً با کلیک روی جعبه‌های انتخاب، کامنت را به‌روزرسانی کنید — نیازی نیست خود مارک‌داون را مستقیماً ویرایش کنید تا وظایف را تیک بزنید.

علاوه بر این، گیت‌هاب در مسائل و درخواست‌های کشش به دنبال فهرست‌های وظایف می‌گردد و آن‌ها را به صورت فراداده (metadata) در صفحاتی که لیست می‌کنند نمایش می‌دهد. برای مثال، اگر یک درخواست کشش با وظایف داشته باشید و صفحه نمای کلی تمام درخواست‌های کشش را ببینید، می‌توانید میزان پیشرفت آن را مشاهده کنید. این به افراد کمک می‌کند درخواست‌های کشش را به وظایف خردتر تقسیم کنند و دیگران را در جریان پیشرفت شاخه قرار دهد. می‌توانید نمونه‌ای از این را در Task list summary in the Pull Request list ببینید.

Task list summary in the Pull Request list
نمودار 103. Task list summary in the Pull Request list

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

قطعه‌های کد (Code Snippets)

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

برای افزودن قطعه کد باید آن را در بک‌تیک (backticks) «محصور» کنید.

```java
for(int i=0 ; i < 5 ; i++)
{
   System.out.println("i is : " + i);
}
```
 اگر نام یک زبان برنامه‌نویسی مثل «java» را اضافه کنید، همان‌طور که در مثال بالا انجام دادیم، گیت‌هاب نیز سعی می‌کند کد را با برجسته‌سازی نحوی نمایش دهد.
در مورد مثال بالا، خروجی به صورت <<_md_code>> خواهد بود.
Rendered fenced code example
نمودار 104. Rendered fenced code example

نقل قول (Quoting)

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

نقل قول‌ها چیزی شبیه به این هستند:

> Whether 'tis Nobler in the mind to suffer
> The Slings and Arrows of outrageous Fortune,

How big are these slings and in particular, these arrows?

وقتی نمایش داده شوند، نظر به صورت Rendered quoting example دیده خواهد شد.

Rendered quoting example
نمودار 105. Rendered quoting example

ایموجی (Emoji)

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

Emoji autocompleter in action
نمودار 106. Emoji autocompleter in action

ایموجی‌ها به شکل :<name>: در هر جای نظر قابل استفاده هستند. برای مثال، می‌توانید چیزی شبیه به این بنویسید:

I :eyes: that :bug: and I :cold_sweat:.

:trophy: for :microscope: it.

:+1: and :sparkles: on this :ship:, it's :fire::poop:!

:clap::tada::panda_face:

زمانی که نمایش داده شود، چیزی شبیه Heavy emoji commenting خواهد بود.

Heavy emoji commenting
نمودار 107. Heavy emoji commenting

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

یادداشت

امروزه سرویس‌های وب زیادی از کاراکترهای ایموجی استفاده می‌کنند. یک راهنمای کامل و مفید برای پیدا کردن ایموجی‌های مناسب، در لینک زیر موجود است:

https://www.webfx.com/tools/emoji-cheat-sheet/

تصاویر (Images)

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

Drag and drop images to upload them and auto-embed them
نمودار 108. Drag and drop images to upload them and auto-embed them

اگر به Drag and drop images to upload them and auto-embed them نگاه کنید، می‌توانید یک راهنمای کوچک با عنوان «Parsed as Markdown» را بالای ناحیه متن ببینید. کلیک روی آن، یک راهنمای کامل از همه قابلیت‌های Markdown روی گیت‌هاب را به شما نشان می‌دهد.

به‌روز نگه داشتن مخزن عمومی گیت‌هاب شما (Keep your GitHub public repository up-to-date)

پس از فورک کردن یک مخزن گیت‌هاب، مخزن شما (یا همان «فورک» شما) به‌صورت مستقل از مخزن اصلی وجود خواهد داشت. به‌خصوص وقتی مخزن اصلی کامیت‌های جدیدی دارد، گیت‌هاب با پیامی مانند زیر به شما اطلاع می‌دهد:

This branch is 5 commits behind progit:master.

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

یکی از روش‌های انجام این کار بدون نیاز به تنظیمات خاص این است که: برای مثال، اگر شما از https://github.com/progit/progit2.git فورک گرفته‌اید، می‌توانید شاخه‌ی master خود را به این شکل به‌روز نگه دارید:

$ git checkout master (1)
$ git pull https://github.com/progit/progit2.git (2)
$ git push origin master (3)

  1. اگر روی شاخه‌ای دیگر بودید، به شاخهٔ master بازگردید.

  2. تغییرات را از https://github.com/progit/progit2.git دریافت کرده و با شاخهٔ master ادغام کنید.

  3. شاخهٔ master خود را به مخزن origin ارسال کنید.

این روش کار می‌کند، اما هر بار باید آدرس URL دریافت را به صورت کامل وارد کنید که کمی خسته‌کننده است. می‌توانید با کمی تنظیمات این کار را خودکار کنید

$ git remote add progit https://github.com/progit/progit2.git (1)
$ git fetch progit (2)
$ git branch --set-upstream-to=progit/master master (3)
$ git config --local remote.pushDefault origin (4)

  1. مخزن منبع را اضافه کرده و نامی برای آن انتخاب کنید. در اینجا من نام progit را انتخاب کرده‌ام.

  2. مرجع شاخه‌های progit، به ویژه master را دریافت کنید.

  3. شاخهٔ master خود را طوری تنظیم کنید که از مخزن راه دور progit دریافت کند.

  4. مخزن پیش‌فرض برای ارسال تغییرات را روی origin تعریف کنید.

پس از انجام این تنظیمات، روند کار بسیار ساده‌تر می‌شود:

$ git checkout master (1)
$ git pull (2)
$ git push (3)

  1. اگر روی شاخه‌ای دیگر بودید، به شاخهٔ master بازگردید.

  2. تغییرات را از progit دریافت کرده و با شاخهٔ master ادغام کنید.

  3. شاخهٔ master خود را به مخزن origin ارسال کنید.

این روش ممکن است مفید باشد، اما بدون معایب نیست. گیت با خوشحالی این کار را به صورت پنهان برای شما انجام می‌دهد، اما اگر شما مستقیماً روی master کامیت بزنید، سپس از progit دریافت کنید و بعد به origin ارسال کنید، هشدار نخواهد داد — همهٔ این عملیات‌ها با این تنظیمات معتبر هستند. بنابراین باید مراقب باشید که هرگز مستقیماً روی master کامیت نزنید، چون این شاخه عملاً متعلق به مخزن بالادستی است.

scroll-to-top