سه سال پیش من اولین پروژه منبع باز خود را برای Hacktoberfest حفظ کردم. به‌عنوان یک نگهدارنده، زمان و تلاشی که برای نوشتن مسائل خوب برای همکارانم لازم است را دست کم گرفتم. چیزی که در آن سال آموختم این بود که نوشتن مسائل شکل مهمی از ارتباط است و به عنوان یک مشارکت کننده، می تواند مهارت ارزشمندی برای ایجاد روابط و حمایت از نگهبانان باشد. اگر می‌خواهید در متن باز مشارکت کنید، یکی از راه‌های شروع این است که مشکلاتی را بنویسید که اشکالات را گزارش می‌کند، ویژگی‌ها را درخواست می‌کند یا بهبودهایی را پیشنهاد می‌کند.
درک هدف موضوع
مسائل اغلب نقطه شروع ارتباط هستند. این فرصتی است برای برقراری ارتباط با نگهبانان یا برای نگهبانان برای برقراری ارتباط با نیازها به مشارکت کنندگان. معمولاً یک ایده اصلی در هر شماره همراه با توضیح وجود دارد. به عنوان مثال، یک گزارش باگ به یک باگ رسیدگی می کند. یک درخواست ویژگی یک ویژگی را مشخص می کند.
عناصر یک مسئله خوب
یک موضوع خوب باید چندین عنصر کلیدی داشته باشد که به بیان واضح و مختصر مشکل یا پیشنهاد کمک کند. این عناصر عبارتند از:
- عنوان واضح و مختصر: عنوان باید موضوع را به گونه ای توصیف کند که به راحتی قابل درک باشد.
- شرح تفصیلی: توضیحات باید شامل توضیح مفصلی از موضوع باشد. استفاده از زبان واضح و مختصر، خاص بودن، اجتناب از فرضیات، اجتناب از زبان مبهم یا مبهم، و محترمانه و حرفه ای بودن بسیار مهم است. در آخر، در صورت نیاز اطلاعات تکمیلی برای روشن شدن موضوع ارائه دهید.
- تصاویر: اسکرین‌شات‌ها، گیف‌ها، ویدیوها یا سایر تصاویر می‌توانند در نشان دادن مشکل مفید باشند.
- اطلاعات متنی: هر گونه اطلاعات اضافی را در مورد محیط یا سیستمی که تحت تأثیر موضوع قرار گرفته است ارائه دهید.
- راه حل پیشنهادی: اگر ایده ای برای نحوه رسیدگی به این مشکل دارید، آن را در موضوع خود بگنجانید.
عناصر گزارش اشکال خوب
برای گزارش های اشکال، عموماً باید اطلاعات زیر را نیز درج کنید:
- مراحل بازتولید باگ
- محیط کار شما (سیستم عامل و غیره)
- مرورگری که از آن استفاده می کنید
- هر گونه اسکرین شات، بازتولید ویدیو، کد یا زمینه قابل اجرا
عناصر یک درخواست ویژگی خوب
برای درخواست های ویژگی، باید به نگهدار کمک کنید تا بفهمد چرا این ویژگی مهم است. به طور کلی باید اطلاعات زیر را در نظر بگیرید:
- نوع ویژگی (اسناد، refactor، سبک، ویژگی کد و غیره)
- وضعیت فعلی برنامه و راه حلی که با ویژگی خود پیشنهاد می کنید
- هر زمینه اطلاعات اضافی، از جمله جایگزین هایی که در نظر گرفته اید
قالب ها را صادر کنید
برخی از مخازن از الگوهای مسئله برای کمک به شما در نوشتن یک مسئله استفاده می کنند. به عنوان مثال، در OpenSauced، ما الگوهایی برای گزارش های اشکال و درخواست های ویژگی داریم (نشان داده شده در زیر). الگوها کمک می کنند تا اطمینان حاصل شود که نگهدارنده تمام اطلاعات مورد نیاز برای برقراری ارتباط با مشارکت کنندگان را دریافت می کند. اگر الگوهایی وجود دارد، استفاده از آنها به جای شروع با یک موضوع خالی مهم است.
نمونه راهنما
گاهی اوقات بهترین راه برای یادگیری نگاه کردن به مثال‌ها است، بنابراین می‌خواهیم این شماره ریمیکس را از نیک تیلور بررسی کنیم.
ما هر یک از عناصر یک مشکل خوب و گزارش اشکال را مرور خواهیم کرد.
عنوان واضح و مختصر
TypeError: بدنه هنگام استفاده از Remix (experimental-netlify-edge) Actions غیرقابل استفاده است
توضیحات مفصل و مراحل بازتولید اشکال
در شماره، نیک چند مرحله کلیدی را پوشش می دهد:
- او از چه نسخه ای از ریمیکس استفاده می کند
- مراحل بازتولید، شامل فهرست شماره‌دار، تکه‌های کد، اسکرین‌شات‌ها و پیوندی به بحث Discord با زمینه بیشتر.
- رفتار مورد انتظار
- رفتار واقعی با اسکرین شات از پیام خطا.
تصاویری
در توضیح این مشکل، یک اسکرین شات از ظاهر آن هنگام اجرای محلی و تصویری از نحوه ظاهر آن در Postman وجود دارد.
راه حل پیشنهادی
اگرچه مشکل اولیه شامل راه حل پیشنهادی نمی شود، نیک به بررسی آنچه در حال رخ دادن است می پردازد و ارتباط را در نظرات حفظ می کند. به عنوان بخشی از تحقیقات، او یک مخزن ایجاد کرد تا به نگهبانان کمک کند آن را بررسی کنند و رویکرد خود را در نظر خود به اشتراک گذاشت.
محیط کار
نیک نسخه Remix را به اشتراک می‌گذارد، نسخه‌های Node را که امتحان کرده است، و شامل نصب Netlify CLI نیز می‌شود.
گفتگو
نیک موضوع را با گزارش اشکال خاتمه نداد. اگر از موضوع فراتر بروید، خواهید دید که او به گفتگو ادامه داد و به یک مکالمه در سازمان Discord اشاره کرد و تحقیقات خود را در مورد باگ و راه حل ها. او با یافتن اطلاعات بیشتر، به‌روزرسانی‌ها را انجام می‌دهد، قطعه‌های کدی را برای متن‌سازی ارائه می‌کند، و نگه‌دارندگان را به عنوان بخشی از گفتگو و همچنین دیگرانی را که مشارکت داشته‌اند، برچسب‌گذاری می‌کند.
بهتر از همه، او از عضو تیمی که در رفع مشکل کمک کرده حمایت می کند.
نوشتن مسائل خوب بخش مهمی از ارتباط موثر هم در نحوه ساختن موضوع و هم در نحوه ارتباط شما پس از باز شدن موضوع است. این یک راه عالی برای نشان دادن مهارت های ارتباطی و تحقیقاتی شما است. و اگر می‌خواهید وارد متن باز شوید، به یاد داشته باشید که اولین مسائل خوب وجود ندارند، مگر اینکه خودتان آنها را بسازید.
