issue טוב ב-GitHub נותן למתחזק את כל מה שהוא צריך כדי לשחזר את הבעיה שלכם ושום דבר שהוא לא צריך. לפני שאתם פותחים אחד, חפשו issues קיימים; אז השתמשו בתבנית ה-issue של המאגר, כתבו כותרת ספציפית, וכללו דוגמה מינימלית שניתן לשחזר, את הגרסאות המדויקות שלכם, ומה ציפיתם לעומת מה שבאמת קרה. שמרו על בעיה אחת לכל issue, עצבו אותו עם code fences של markdown, והיו סבלניים – רוב המתחזקים הם מתנדבים. issue שמישהו יכול לשחזר בשתי דקות הוא issue שמתוקן.
איך לכתוב issue טוב ב-GitHub: שלב אחר שלב
- חפשו קודם issues פתוחים וסגורים. הבאג שלכם אולי כבר דווח, תוקן או הוסבר – הגיבו שם במקום לפתוח כפילות.
- בדקו את CONTRIBUTING.md ואת תבניות ה-issue. פרויקטים רבים מנתבים שאלות ל-Discussions ושומרים את ה-issues לבאגים ולפיצ’רים.
- בחרו את התבנית הנכונה ובעיה אחת. בחרו “bug report” או “feature request”, והגישו issue נפרד לכל בעיה נבדלת.
- כתבו כותרת ספציפית. סכמו את הסימפטום בפועל, כמו הודעת commit טובה – לא “זה לא עובד”.
- הוסיפו דוגמה מינימלית שניתן לשחזר. ספקו את הקטע הקטן ביותר שניתן להריץ, מאגר לדוגמה, או את הצעדים המדויקים שמפעילים את הבאג.
- ציינו התנהגות צפויה לעומת בפועל ואת הסביבה שלכם. כללו את גרסת החבילה המדויקת, מערכת ההפעלה, וה-runtime, וגם את השגיאה המלאה או הלוגים בבלוק קוד.
- הגישו, ואז הישארו זמינים. ענו על שאלות ההמשך של המתחזק כדי שה-issue לא יתיישן.
מה כן ומה לא
מה כן:
- חפשו issues פתוחים וגם סגורים לפני שאתם מגישים.
- עקבו אחר תבנית ה-issue ומדריך התרומה של המאגר.
- כתבו issue אחד ברור וספציפי לכל בעיה.
- כללו דוגמה מינימלית שניתן לשחזר וגרסאות מדויקות.
- השתמשו ב-code fences של markdown לקוד, ללוגים ול-stack traces.
מה לא:
- לפתוח כפילות בלי לבדוק קודם.
- להגיש issue מעורפל של “לא עובד” בלי שחזור.
- לדחוס כמה באגים לא קשורים ל-issue אחד.
- לתייג (@mention) או לשלוח הודעה פרטית למתחזקים כדי לדרוש תיקון מהיר.
- לערום תגובות “+1” או “גם לי” – השתמשו בתגובת 👍 במקום.
חפשו לפני שאתם מגישים
issues פתוחים הם רק חצי מהתמונה – חפשו גם ב-issues הסגורים. issue סגור לרוב מחזיק את התיקון, את ה-workaround, או את הסיבה של המתחזק ל"won’t fix". אם מצאתם issue פתוח שמתאים, הוסיפו שם את פרטי השחזור או הסביבה שלכם במקום לפתוח כפילות; זה מרכז את האות שהמתחזקים משתמשים בו כדי לתעדף. השתמשו בחיפוש ה-issues של GitHub עם qualifiers כמו is:issue your error text כדי לחתוך דרך הרעש.
השתמשו בתבנית ה-issue (ובערוץ הנכון)
רוב המאגרים המבוססים מגיעים עם תבניות issue – טופס bug-report, טופס feature-request, ולפעמים אפשרות של issue ריק שכבויה בכוונה. מלאו את התבנית במלואה במקום למחוק את ההנחיות; כל שדה נמצא שם כי המתחזקים נמאס להם לבקש אותו.
לפני זה, רפרפו על CONTRIBUTING.md. פרויקטים רבים שולחים שאלות שימוש ל-GitHub Discussions, לפורום קהילתי, או ל-Stack Overflow, ושומרים את מערכת ה-issues אך ורק לבאגים ולפיצ’רים. לפרסם שאלת “איך עושים” כ-issue במאגרים האלה לרוב פשוט גורם לכך שהוא ייסגר עם קישור למקום הנכון.
הלב של issue טוב: דוגמה שניתן לשחזר
כל השאר משני לשאלה האחת הזו: האם המתחזק יכול לשחזר את הבעיה שלכם? תנו להם דוגמה מינימלית שניתן לשחזר – הקטע הקטן ביותר שניתן להריץ, מאגר לדוגמה, או רצף הצעדים המדויק שמפעיל את הבאג על התקנה נקייה. “זה קורס לפעמים” לא ניתן לפעולה; “הרצת npm test על clone טרי של ה-repro הזה בן 15 השורות זורקת את ה-stack trace למטה” כן.
אם אתם מדווחים על באג ולא מבקשים פיצ’ר, שימו את הדוגמה שלכם ישירות בתבנית דיווח הבאג שלנו – שדות ה"Steps to reproduce" וה"Environment" שלה בנויים בדיוק לזה.
כללו גרסאות וסביבה
“Latest” זו לא גרסה. תנו את גרסת החבילה המדויקת (או commit SHA), את מערכת ההפעלה, ואת גרסת השפה או ה-runtime – v2.4.1, macOS 14.5, Node 20.11. באגים לעתים קרובות תלויים בגרסה, ומתחזק שלא יכול לדעת באיזה release אתם יבזבז הלוך-חזור רק כדי לשאול. הדביקו את הודעת השגיאה המלאה וכל לוג רלוונטי; שגיאה חתוכה לרוב מסתירה את השורה שבאמת חשובה.
עצבו את זה ברצינות
issues של GitHub הם markdown, אז השתמשו בו. עטפו קוד, פקודות ו-stack traces ב-fences של שלושה backticks עם רמז שפה להדגשת תחביר. כווצו לוגים ארוכים מאוד בתוך בלוק <details> כדי שה-issue יישאר קריא. תייגו את החלקים המרכזיים – Expected, Actual, Steps to reproduce – וקשרו לשורות קוד ספציפיות עם permalinks (לחצו y ב-GitHub כדי לקבל URL מקובע ל-commit). issue נקי וקל לסריקה עובר triage מהר יותר מקיר של טקסט.
זכרו מי בצד השני
רוב המתחזקים הם מתנדבים ללא תשלום שעובדים על הפרויקט בזמנם הפנוי, וזה מעצב את הנימוסים. אל תתייגו (@mention) אותם או תשלחו להם הודעה פרטית כדי לדרוש תיקון, ואל תוסיפו תגובות “יש עדכון?” שרק יוצרות רעש. דלגו על “+1” ו"גם לי" לגמרי – הוסיפו תגובת 👍 ל-issue המקורי כדי שהמתחזקים יוכלו לאמוד ביקוש בלי שיטפון של התראות. הגיבו רק כשיש לכם משהו חדש: שחזור נוסף, סביבה שונה, או workaround.
ואם אתם חושדים בפרצת אבטחה, אל תפתחו issue ציבורי בכלל. השתמשו בדיווח האבטחה הפרטי של המאגר – בדרך כלל מדיניות SECURITY.md או הלשונית “Report a vulnerability” של GitHub – כדי שהפרצה לא תשודר לפני שהיא מתוקנת.
הנוסחה עדיין עובדת
issue מצוין ב-GitHub הוא פשוט נוסחת Skip The Ask בהקשר של מפתח:
- המצב שלכם – הפרויקט, הגרסה והסביבה שאתם מריצים
- הדיווח או הבקשה הספציפית שלכם – הבאג או הפיצ’ר המדויק, בכותרת ברורה
- פרטים רלוונטיים – דוגמה מינימלית שניתן לשחזר, התנהגות צפויה לעומת בפועל, והשגיאה המלאה
תנו למתחזקים בעיה שהם יכולים לשחזר ועשיתם 90% מהעבודה לקראת תיקון שלה.
שואלים שאלת “איך עושים” במקום לדווח על באג? מדריך ה-Stack Overflow שלנו מכסה את המקרה הזה. לעקרונות האוניברסליים שמאחורי כל פלטפורמה, ראו את המדריך המלא שלנו לשאילת שאלות טובות יותר באינטרנט.