راهنما:گیت

در این صفحه نحوهٔ فرستادن پچ برای تغییر تنظیمات سامانه به صورت خلاصه و کاربردی شرح داده می‌شود.

گیت

لوگوی گیت

اکثر تنظیمات سامانه با تغییر فایل‌های متنی به سادگی امکان‌پذیر است و نیاز به دانش خاصی هم نیست. مثلاً برای تغییر زبان ویکی‌رأی از انگلیسی به فارسی فقط کافی است در صفحهٔ InitialiseSettings.php مقدار wgLanguageCode برای votewiki از en به fa عوض شود. بنابراین انجام خود تغییر معمولاً کار بسیار ساده‌ای است. آنچه در اینجا قصد داریم توضیح دهیم انجام کارهای ساده با نرم‌افزار گیت است. گیت در حال حاضر معروف‌ترین نرم‌افزار کنترل نسخه است. ویکی‌پدین‌ها معمولاً درک خوبی از مفهوم کنترل نسخه دارند چون کار ویکی‌پدیا هم با کنترل نسخه گره خورده و کاربران به‌خوبی از اهمیت کار با تاریخچهٔ مقالات آگاهند. ویکی‌پدین‌ها خوب می‌دانند که چیزی از ویکی‌پدیا حذف نمی‌شود چون همه‌چیز از طریق تاریخچه قابل دستیابی است و امکان آسیب رساندن جدی به محتوای ویکی‌پدیا نیز وجود ندارد چون به‌راحتی می‌توان مقالات را به نسخه‌های صحیح بازگرداند. کل نقشی که قرار است گیت در اینجا ایفا کند نیز ایجاد یک تاریخچه و حفاظت از نسخه‌هاست.

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

me@linuxbox:~$ git config --global user.name "4nn1l2"
me@linuxbox:~$ git config --global user.email 4nn1l2.vv1x1@gmail.com

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

تغییر تنظیمات سامانه

اولین قدم ساخت حساب کاربری در ویکی‌تِک است: wikitech:Special:CreateAccount

ایجاد مخزن محلی: شبیه‌سازی

اکثر تنظیماتی که انجام خواهیم داد در همان صفحهٔ InitialiseSettings.php است و این صفحه در مخزن operations/mediawiki-config قرار دارد. می‌خواهیم نسخه‌ای محلی از این مخزن را در کامپیوترمان داشته باشیم تا تنظیمات را روی آن انجام دهیم.

به https://gerrit.wikimedia.org/ بروید، سپس BROWSE و سپس Repositories. در قسمت Filter عبارت operations/mediawiki-config را وارد کنید و روی اولین نتیجه کلیک کنید. در بالای صفحه در قسمت Download زیر clone دستور و آدرس مورد نظر نوشته شده است. همان را کپی کنید.

در یک مکان دلخواه مناسب (مثلاً پوشهٔ wiki در home)، ترمینال را باز کنید و فرمانی که کپی کرده بودید را پیست کنید.

me@linuxbox:~/wiki$ git clone "https://gerrit.wikimedia.org/r/operations/mediawiki-config"

فایل‌هایی با حجم تقریبی ۱۵۰ مگابایت دانلود می‌شوند. درون پوشهٔ wiki پوشهٔ جدیدی به نام mediawiki-config ایجاد می‌شود که محل فعالیت ماست. به این پوشه بروید.

me@linuxbox:~/wiki$ cd mediawiki-config

ایجاد شاخهٔ موضوعی

بهتر است تغییرات را روی یک شاخهٔ اختصاصی انجام دهید، نه شاخهٔ master. قدرت نرم‌افزار گیت در زمینهٔ شاخه‌هایش است. نامی که برای شاخهٔ جدید انتخاب می‌کنید مهم نیست ولی بهتر است شمارهٔ تیکت مربوطه در فابریکاتور باشد، مثلاً T292685.

me@linuxbox:~/wiki/mediawiki-config$ git branch T292685

از شاخهٔ master که به صورت پیش‌فرض در آن قرار دارید به شاخهٔ جدید بروید.

me@linuxbox:~/wiki/mediawiki-config$ git switch T292685

switch فرمانی است که در نسخه‌های جدیدتر گیت اضافه شده است. قبلاً از checkout استفاده می‌شد. کاری که دقیقاً چک‌اوت انجام می‌دهد، آپدیت کردن working directory و staging index است، نه تعویض شاخه. فهم معنای چک‌اوت که همین حالا هم در بسیاری از صفحات راهنمای گیت به‌کرات دیده می‌شود، مخصوصاً برای تازه‌کاران ساده نیست، و در نهایت به نفع معرفی فرمان‌های جدید چون switch و restore که شهودی‌تر هستند تقریباً کنار گذاشته شده است. چک‌اوت از اصطلاح‌هایی است که از نسل‌های قدیمی نرم‌افزارهای کنترل نسخه به نسل‌های جدیدتر کنترل نسخه توزیع‌شده راه یافته است. قبلاً که کنترل نسخه به صورت متمرکز (در مقابل توزیع‌شده) انجام می‌شد، مخزن مرکزی را می‌شد به یک کتابخانه تشبیه کرد که کاربران برخی فایل‌ها را از آن امانت می‌گرفتند (که در این حالت آن فایل قفل می‌شد و دیگران به آن دسترسی نداشتند، همانطور که کتاب به امانت‌رفته در دسترس دیگران نیست) و پس از آنکه کارشان با آن فایل تمام می‌شد آن را تحویل می‌دادند. به جز شاخه، می‌توان کامیت و تگ و کلاً هر شیء درخت‌مانندی را هم چک‌اوت کرد.

اعمال تغییر به صورت محلی

فایل مورد نظر یعنی InitialiseSettings.php در پوشهٔ wmf-config قرار دارد. آن را با هر ویرایشگر متن دلخواه (از جمله جی‌ادیت) ویرایش کنید، یعنی به سادگی مقدار wgLanguageCode را برای votewiki از en به fa تغییر دهید و البته به تیکت فابریکاتور نیز در قالب یک کامنت ارجاع دهید.

قبل از تغییر

	'votewiki' => 'en',

بعد از تغییر

	'votewiki' => 'fa', // T292685

و البته حواستان باشد که فاصله‌ها را رعایت کنید و کثیف‌کاری نکنید چون در غیر این صورت ممکن است پچ را قبول نکنند و از شما بخواهند فایل را دوباره ویرایش کنید تا تر و تمیز باشد و مثلاً اسپیس اضافه نداشته باشد. برای چک کردن فواصل اضافه می‌توانید در همین مرحله از فرمان git diff --check استفاده کنید. git diff --color-words هم می‌تواند تغییرات را بهتر نمایش دهد.

کامیت زدن

حالا به پوشهٔ mediawiki-config بازگردید و در ترمینال فرمان زیر را وارد کنید.

me@linuxbox:~/wiki/mediawiki-config$ git status

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

On branch T292685
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   wmf-config/InitialiseSettings.php

no changes added to commit (use "git add" and/or "git commit -a")

فرمان git status بسیار کاربردی است. خواهید دید که پس از گرم شدن دستتان بارها از این فرمان استفاده خواهید کرد. معنی status روشن کردن آخرین وضعیت پوشه است.

حالا کافی است فایلِ تغییرداده‌شده را روی سکو ببرید که این کار با فرمان git add انجام می‌شود. معنی add اضافه کردن این محتوا به کامیت بعدی است.

me@linuxbox:~/wiki/mediawiki-config$ git add wmf-config/InitialiseSettings.php

حالا دوباره git status را وارد کنید تا آخرین وضعیت دستتان بیاید.

On branch T292685
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   wmf-config/InitialiseSettings.php

شرایط برای کامیت زدن مهیاست. فرمان زیر را وارد کنید.

me@linuxbox:~/wiki/mediawiki-config$ git commit

در این مرحله یک ویرایشگر متن باز می‌شود که شما باید خلاصه‌ای از تغییراتی که انجام دادید را در آنجا بنویسید و به شمارهٔ تیکت فابریکاتور نیز ارجاع دهید. به احتمال زیاد، ویرایشگر پیش‌فرض ویم است که کار کردن با آن عجیب مشقت‌آور است. اگر اینطور است فقط سعی کنید از آن خارج شوید. موفق باشید ;-) هیچ دلیلی ندارد که مشقت کار کردن با این ویرایشگر را تحمل کنید مگر اینکه از قبل با آن آشنا بوده و به عجایب و غرایب آن عادت کرده باشید (که در این صورت یا از پیش‌کسوت‌ها هستید [🙇]، یا خیلی خُلید یا صرفاً می‌خواهید پُز بدهید! اما اگر هیچ‌یک از این شرایط برقرار نیست، بهتر است تنظیمات گیت را تغییر دهید تا از یک ویرایشگر «معقول‌تر» و امروزی‌تر استفاده کند. مثلاً اینجا gedit انتخاب شده، ولی می‌توانید از nano یا حتی code (اگر ویژوال استودیو کد را نصب دارید) استفاده کنید.

me@linuxbox:~/wiki/mediawiki-config$ git config --global core.editor gedit

دوباره فرمان git commit را اجرا کنید تا بتوانید خلاصه ویرایش بنویسید. بیشتر از ده کلمه ننویسید. در وجه امری بنویسید ولی پایانش نقطه نگذارید. مثلاً Change votewiki language to Farsi مناسب است. یک خط خالی فاصله بیندازید و زیرش شمارهٔ تیکت مربوطه در فابریکاتور را به شکل Bug: T292685 بنویسید. صفحه را ذخیره کنید و از ویرایشگر خارج شوید.

انتشار تغییر در مخزن دور

گام آخر آپدیت کردن مخزن دور (در مقابل مخزن محلی شما روی کامپیورتان، یا به عبارتی دیگر «مخزن اصلی» روی اینترنت) است.

me@linuxbox:~/wiki/mediawiki-config$ git push origin HEAD:refs/for/master

در این مرحله نام کاربری و گذرواژه‌تان درخواست می‌شود. نام کاربری‌تان همان UNIX shell username است که هنگام ایجاد حساب کاربری در ویکی‌تِک (آخرین فیلد) وارد کردید و شاید متفاوت از نام کاربری‌تان در ویکی‌تِک باشد (و لزوماً ربطی به نام کاربری گیت که اوایل این صفحه ذکرش رفت یا نام کاربری‌تان در ویکی‌پدیا نیز ندارد) مثلاً نام کاربری راقم این سطور nn1l2 است. برای گذرواژه، وارد حساب کاربری‌تان در گریت شوید (با همان نام کاربری و گذرواژه ویکی‌تک) و سپس از قسمت Settings حساب کاربری‌تان GENERATE NEW PASSWORD را بزنید تا گذرواژه یک‌بار مصرف تحویل بگیرید. البته اگر از SSH استفاده کنید (که در ادامه توضیح داده خواهد شد)، نیاز به وارد کردن حساب کاربری و گذرواژه نیست.

اگر همه‌چیز با موفقیت پیش رود، در این مرحله باید gerritbot تیکت فابریکاتور را با گذاشتن یک پیام آپدیت کند. مدتی صبر کنید تا دیگران تغییراتتان را بررسی و تأیید کنند. اگر طول کشید، از یکی دو نفر به صورت دستی از طریق گریت تقاضای بررسی کنید. اگر واکنش‌ها مثبت بود، به wikitech:Deployments بروید و از میان backport windowها یک زمان مناسب که خودتان هم آن زمان آنلاین هستید را انتخاب کنید و نوبت بگیرید (مثال). در نهایت به wikitech:WikimediaDebug بروید و افزونه‌ای که آنجا معرفی شده را برای مرورگر کروم یا فایرفاکس نصب کنید.

در زمان مقرر به کانال آی‌آرسی #wikimedia-operations ^اتصال بروید و منتظر توسعه‌دهندهٔ مسئول بمانید. او به شما خواهد گفت که با کمک افزونه‌ای که روی مرورگرتان نصب کردید، تغییرات اعمال‌شده را تست کنید. کافی است دکمهٔ روشن آن افزونه را بزنید و آن سروری که توسعه‌دهنده به شما می‌گوید را انتخاب کنید. اگر همه‌چیز درست پیش رفته باشد الان باید ویکی‌رأی را به زبان فارسی ببینید (مواظب کَش باشید). به او بگویید تست مطابق انتظار پیش رفته است تا در نهایت تغییرات اعمال شوند. Stashbot تیکت مربوطه در فابریکاتور را با گذاشتن یک پیام آپدیت خواهد کرد.

حالا می‌توانید شاخه‌ای که ایجاد کرده بودید را حذف کنید چون دیگر به آن نیازی نیست و تغییرات مورد نظر نیز در آپدیت بعدی مخزن محلی از روی مخزن دور مجدداً در مخزن محلی شما به وجود خواهند آمد. برای حذف شاخه لازم است که ابتدا به شاخهٔ دیگری (مثلاً master) بروید.

me@linuxbox:~/wiki/mediawiki-config$ git switch master
me@linuxbox:~/wiki/mediawiki-config$ git branch -D T292685

تغییر بعدی

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

me@linuxbox:~/wiki/mediawiki-config$ git pull

در نسخه‌های تازهٔ گیت (۲٫۲۷ به بعد)، پس از اجرای این فرمان پیامی می‌آید که می‌خواهد بین rebase و merge یکی را انتخاب کنید. rebase مزیت خاصی جز بازنویسی تمیز تاریخچه ندارد [و کلاً در هر زمینه‌ای بازنویسی تاریخ عمل چندانی مطلوبی نیست!] و نیاز نیست در این راهنمای مقدماتی به آن پرداخت. بهتر است از همان تنظیمات پیش‌فرض نسخ قبلی استفاده کرد یعنی git config pull.rebase false

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

me@linuxbox:~/wiki/mediawiki-config$ git reset --hard origin/master

قبل از انجام این کار بایستی قبلاً با استفاده از git fetch یا git pull حتماً شاخهٔ محلی origin/master را از روی مخزن دور به روز کرده باشید وگرنه فایده‌ای ندارد. هرچند ممکن است گیج‌کننده به نظر آید، این توضیح ضروری است که origin/master هم در مخزن محلی است و هم در مخزن دور و هنگام به کار بردن فرمان reset شما صرفاً وضعیت را به وضعیت شاخهٔ origin/master محلی بر می‌گردانید. بنابراین لازم است که وضعیت خود این شاخه اوکی باشد. توضیح دوم اینکه فرق fetch با pull در این است که fetch صرفاً origin/master محلی را با مخزن دور همگام می‌کند (تاریخچهٔ مخزن دور را به صورت محلی در دسترس شما قرار می‌دهد)، ولی pull علاوه بر این کار عمل ادغام را نیز انجام خواهد داد، به عبارت دیگر pull=fetch+merge

چرا کامیتی که در مخزن محلی زده‌اید و بعداً در مخزن دور منتشر کرده‌اید، با وجود همگام‌سازی مخزن‌ها، مخزن محلی را جلو انداخته؟ مگر کامیت گرفته‌شده از مخزن دور قبلاً در مخزن محلی نبوده؟ چون SHA-1 کامیت‌ها تغییر کرده و سیستم این‌ها را به دو عنوان کامیت مجزا حساب خواهد کرد. چرا SHA-1 کامیت تغییر کرده؟ چون بین فرستادن پچ تا اعمال آن توسط دولوپر فاصله افتاده، شاید دولوپر کامیت را rebase کرده باشد و در نتیجه والد کامیت تغییر کرده باشد و لاجرم SHA-1ش نیز تغییر کرده است. حتی اگر rebase هم نکرده باشد، نام و تاریخ commit (برخلاف author) قطعاً به نام دولوپر و زمان جدید تغییر خواهد کرد و SHA-1 کامیت هم ۱۰۰٪ تغییر خواهد کرد، بنابراین نگه داشتن کامیت قبلی بی‌فایده است و به عنوان یک زائده بیرون می‌زند و مخزن محلی را جلو می‌اندازد.

ولی اگر طبق توصیهٔ این راهنما از همان اول یک شاخهٔ اختصاصی برای تیکت مربوطه ایجاد کنید اصلاً به این مشکل و دردسرهای احتمالی آن بر نخواهید خورد.

SSH

اگر همچنان می‌خواهید به فرستادن پچ ادامه دهید، وارد کردن نام کاربری و گذرواژه به کاری خسته‌کننده تبدیل می‌شود (مخصوصاً که گذرواژه به‌یادماندنی نیست و هر بار باید از نو تحویل گرفته شود). راه‌حل استفاده از SSH است.

me@linuxbox:~$ ssh-keygen -t rsa

گذرعبارت را هم وارد کنید یا خالی بگذارید. حالا باید دو فایل در پوشهٔ مخفی ‎.ssh در پوشهٔ خانهٔ کامپیوترتان قرار گرفته باشد. محتوای id_rsa.pub را عیناً در قسمت SSH keys تنظیمات حساب کاربری‌تان در گریت کپی کنید.

در نهایت، باید نشانی مخزن دور را در کامپیوترتان از HTTP به SSH تغییر دهید. به پوشهٔ ‎.git مخزن محلی رفته و فایل config را با یک ویرایشگر دلخواه باز کنید و url را در قسمت [remote "origin"] به مقدار زیر تغییر دهید.

ssh://nn1l2@gerrit.wikimedia.org:29418/operations/mediawiki-config

به جای nn1l2 باید UNIX shell username خودتان را وارد کنید. این آدرس را می‌توانید از مخزن مربوطه در حالی که وارد سامانهٔ گریت شده‌اید (مثلاً https://gerrit.wikimedia.org/r/admin/repos/operations/mediawiki-config) نیز به دست آورید. همان آدرسی که در قسمت SSH از بخش دانلود در بالای صفحه آمده را کپی کنید.

اولین باری که سعی کنید با SSH به مخزن دور وصل شوید (مثلاً با git fetch)، از شما خواسته می‌شود که یک «اثرانگشت» را تأیید کنید که اگر SHA256:j7HQoQ6fIuEgDHjONjI2CZ+2Iwxqgo2Ur5LbPqBgxOU بود yes بزنید و پیش بروید.

git-review

بد نیست (ولی به هیچ‌وجه ضرورتی ندارد) git-review را نیز نصب کنید. فایده‌اش فقط کم کردن زحمت تایپ چند کلید و انجام چند بررسی به صورت خودکار است. پس از نصب، تنظیمات اولیه را نیز انجام دهید.

me@linuxbox:~$ git config --global gitreview.remote origin
me@linuxbox:~$ git config --global gitreview.username "4nn1l2"

مزیتی که دارد این است که در مرحلهٔ انتشار کامیت، می‌توانید به جای

me@linuxbox:~/wiki/mediawiki-config$ git push origin HEAD:refs/for/master

از

me@linuxbox:~/wiki/mediawiki-config$ git review -R

استفاده کنید که مستلزم فشردن چند دکمهٔ کمتر است :) و احتمالاً راحت‌تر به خاطر سپرده می‌شود و قسمت topic در کامیت مربوطه را با نام شاخه‌ای که درون آن هستید به صورت خودکار پر می‌کند. اما توجه کنید که topic را با استفاده از push هم می‌توانید پر کنید. کافی است ‎%topic=‎ را خودتان به انتهای refs/for/master بیفزایید، اینطوری:

me@linuxbox:~/wiki/mediawiki-config$ git push origin HEAD:refs/for/master%topic=T292685

پر کردن تاپیک اهمیت کاربردی ندارد.

جستارهای وابسته

• mw:Gerrit، صفحهٔ گریت در مدیاویکی
  • mw:Gerrit/Tutorial، خودآموز استفاده از گیت و گریت در مدیاویکی
• wikitech:Wikimedia site requests، راهنمای برخی از رایج‌ترین تنظیمات درخواستی
• کتاب راهنمای کامل گیت (Pro Git)
  • مطالعهٔ فصول اول، دوم، سوم، و پنجم نه تنها کافی است، که بسیار بیشتر از آنچه در ویکی‌مدیا به آن نیاز دارید به شما خواهد آموخت.
• برگه‌های تقلب گیت‌هاب و بصری
• خودآموز ویدئویی لینکدین لرنینگ (لیندای سابق): مقدماتی و ادامه