چگونه مشارکت کنیم

خوش‌آمدید

به راهنمای مشارکت در Cloud Native Glossary خوش آمدید و از علاقه شما سپاس‌گزاریم. راه‌های متعددی برای مشارکت در این پروژه وجود دارد که در ادامه با جزئیات آن‌ها آشنا می‌شوید:

1. کار روی یک Issue موجود
2. پیشنهاد اصطلاح‌های جدید
3. به‌روزرسانی اصطلاح‌های فعلی
4. بومی‌سازی Glossary

نمای کلی Glossary CNCF

هدف این Glossary ساده‌سازی فضای Cloud Native — که به پیچیدگی مشهور است — و در نتیجه دسترس‌پذیرتر کردن آن برای همه است.

محتوای Cloud Native Glossary در این مخزن GitHub نگه‌داری می‌شود؛ جایی که فهرست Issueها، Pull Requestها (PR) و گفت‌وگوها درباره Glossary را خواهید یافت.

چه کسانی می‌توانند مشارکت کنند؟

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

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

اگر هنوز متخصص Cloud Native نیستید ولی می‌خواهید مشارکت کنید، پیشنهاد می‌کنیم با فردی متخصص همراه شوید. وقتی او مطمئن شد تعریف دقیق است، شما آماده نخستین مشارکت در Glossary هستید.

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

پیش از آغاز

قبل از شروع مسیر مشارکت در Glossary، این مراحل را انجام دهید:

1. اگر هنوز حسابی ندارید، یک حساب GitHub بسازید.
2. اگر در محیط محلی خود توسعه می‌دهید، مقادیر user.name و user.email را در تنظیمات Git درست تنظیم کنید.
3. هر زمان با git commit Commit می‌زنید، گزینه -s را برای افزودن امضای DCO اضافه کنید. یا این‌که با اجرای git config --global alias.ci "commit -s" یک نام مستعار به gitconfig اضافه کنید.

بهترین رویه‌ها

برای تسهیل فرایند بازبینی، لطفاً از Semantic Line Break استفاده کنید. همچنین توصیه می‌کنیم این برگه تقلب Markdown را برای فرمت‌بندی درست متن در GitHub (مانند لینک، بولد، ایتالیک) بررسی کنید. هنگام نام‌گذاری فایل‌های .md از حروف کوچک و خط تیره به‌جای فاصله استفاده کنید و از پرانتز بپرهیزید.

راهنمای سبک

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

به جامعه Glossary بپیوندید!

با Maintainerها و سایر مشارکت‌کنندگان در کانال #glossary در Slack CNCF در ارتباط باشید — خوشحال می‌شویم شما را ببینیم!

کار روی یک Issue موجود

برای یافتن فهرست Issueهای موجود به Issues مخزن Glossary در GitHub بروید. می‌توانید با استفاده از Labelها (مانند English language، help needed، good first issue) نتایج را فیلتر کنید.

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

پس از انتخاب اصطلاح، روی Issue نظر بگذارید.

علاوه بر آن، Maintainerها را در کانال #glossary در Slack CNCF مطلع کنید و @iamnoah، @nate-double-u، @Seokho Son، @Jihoon Seo و/یا @Junya Okabe را Mention کنید تا درخواست شما دیده شود.

برای مراحل بعدی، به بخش ارسال اصطلاح جدید (ایجاد PR) مراجعه کنید.

نکته: پس از این‌که Maintainerها Issue را به شما Assign کردند، می‌توانید کار را آغاز کنید. در هر زمان فقط یک اصطلاح را می‌توان Claim کرد. کار روی اصطلاحات متعدد باید به‌صورت متوالی باشد؛ ابتدا اصطلاح فعلی را کامل کنید و سپس سراغ بعدی بروید.

پیشنهاد اصطلاح‌های جدید

می‌توانید اصطلاح جدیدی را برای دیگران پیشنهاد دهید یا خودتان تعریف آن را بنویسید. در هر دو حالت باید یک Issue بسازید. برای افزوده‌شدن به Glossary هر اصطلاح جدید باید با تعریف Cloud Native CNCF هم‌خوان باشد. تنها استثنا اصطلاحات پایه‌ای هستند که برای درک مفاهیم Cloud Native لازم‌اند.

در ادامه راهنمای گام‌به‌گام برای افراد ناآشنا با GitHub می‌آید. اگر GitHub Pro هستید، لطفاً این راهنما را مرور کنید تا اطلاعات لازم را درباره موارد زیر به دست آورید:

1. پیدا کردن Templateهای Issue و اصطلاح جدید.
2. Claim کردن Issueها.
3. رفع خطاهای Spell Check.

ساخت Issue

به بخش Issues در مخزن Glossary در GitHub بروید و روی «New issue» کلیک کنید.

از فهرست Templateها گزینه «Request to add a new term (English)» را انتخاب کنید.

واژه پیشنهادی را وارد کنید، به سؤالات پاسخ دهید، گزینه‌ها را تیک بزنید و «Submit new issue» را فشار دهید. اگر فقط پیشنهاد اصطلاح جدید می‌دهید، همین کافی است. اگر می‌خواهید روی تعریف کار کنید، ادامه دهید.

رسیدگی به Issue شما

در مرحله بعد Maintainerها Issue را بررسی می‌کنند تا مشخص شود این اصطلاح باید بخشی از Glossary باشد یا خیر. همه اصطلاحات پذیرفته نمی‌شوند؛ تنها مفاهیم جاافتاده و پرکاربرد Cloud Native در Glossary قرار می‌گیرند.

لطفاً Maintainerها را در Slack مطلع کنید و @iamnoah، @nate-double-u، @Seokho Son، @Jihoon Seo و/یا @Junya Okabe را Mention کنید تا درخواست شما دیده شود. اگر قصد دارید روی تعریف کار کنید، اطلاع دهید تا Issue به شما Assign شود.

ارسال اصطلاح جدید (ایجاد PR)

همان‌طور که در راهنمای سبک آمده، قویاً توصیه می‌کنیم ابتدا پیش‌نویس را در Google Doc یا Word آماده کنید.

پس از آماده شدن متن، به پوشه content (در بخش <>Code) بروید…

… سپس پوشه «en» (برای انگلیسی) یا دو حرف اول زبان موردنظر…

… و فایل _TEMPLATE.md را انتخاب کنید.

محتوا را کپی کنید…

… و به پوشه «en» بازگردید. «Add file» و سپس «Create new file» را انتخاب کنید.

نام اصطلاح را مطابق دستورالعمل‌های بهترین رویه‌ها در URL وارد کنید و در انتها .md اضافه کنید (بدون این پسوند امکان پیش‌نمایش ندارید). حالا Template را در بخش ویرایشگر Paste کنید و متن تعریف خود را جایگزین کنید. برای اطمینان از رعایت Markdown مطابق بهترین رویه‌ها روی «Preview» کلیک کنید.

پایین بروید، پیامی برای Commit بنویسید و وقتی آماده بودید «Commit new file» را بزنید و…

… حالا آماده ایجاد PR هستید:

پس از کلیک روی «Create pull request»، PR شما در تب «Pull requests» ظاهر می‌شود.

به‌روزرسانی اصطلاح موجود

برای به‌روزرسانی یک اصطلاح می‌توانید با ایجاد Issue درخواست تغییر بدهید یا خودتان تغییر دهید و PR ارسال کنید.

درخواست تغییر از طریق Issue

برای اعلام مشکل در یک اصطلاح می‌توانید از گزینه «Report issue» در وب‌سایت CNCF Glossary استفاده کنید. به صفحه اصطلاح موردنظر بروید و روی «Report issue» کلیک کنید؛ یک Issue به‌صورت خودکار ایجاد می‌شود.

پیشنهادها و دلیل نیاز به آن‌ها را توضیح دهید و ارسال کنید؛ همین.

به‌روزرسانی مستقیم اصطلاح

برای اعمال تغییر و ارسال پیشنهاد، روی «Edit this page» کلیک کنید.

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

کمک به بومی‌سازی Glossary

برای بومی‌سازی Glossary به زبان مقصد، به کانال #glossary-localizations در Slack CNCF بپیوندید و پیام بفرستید. می‌توانید به تیم موجود ملحق شوید یا تیم جدیدی تشکیل دهید (برای اطلاع از الزامات، راهنمای بومی‌سازی را بخوانید). لطفاً راهنمای «How to Contribute» مربوط به زبان مقصد را مطالعه کنید تا از جزئیات فرایند مشارکت آن تیم آگاه شوید.

Spell Check

دو دلیل اصلی برای شکست تست Spell Check وجود دارد:

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

برای افزودن واژه جدید به فهرست مراحل زیر را انجام دهید:

1. در PR خود فایل «wordlist.txt» را پیدا کنید.
2. روی «Edit this file» کلیک کنید و واژه‌های جدید را به ترتیب الفبایی اضافه کنید.
3. پیام Commit بنویسید و گزینه «Sign off and propose changes» را انتخاب کنید.

نکته: Spell Check نسبت به بزرگی و کوچکی حروف حساس نیست.

این راهنما بر اساس Templateهای The Good Docs Project به‌روزرسانی شده است.