כיצד לכתוב הודעת התחייבות Git יעילה ושימושית

הודעות Commit הן תיאור קצר של כל commit במערכת בקרת גרסאות כמו Git. כאשר אתה מבצע שינויים בקבצי הפרויקט שלך, עליך לספק הודעה המסבירה מה הם עושים או מדוע ביצעת אותם.

הודעות מחויבות משמשות כצורה של תיעוד ותקשורת. הם ממלאים תפקיד מכריע בשמירה על היסטוריית גרסאות ברורה ומאורגנת של פרויקט. למד כיצד לכתוב הודעות מחויבות טובות ושאר חברי הצוות שלך יעריכו את עבודתך אפילו יותר.

מבנה של הודעת מחויבות טובה

דוגמה טובה להודעת התחייבות כוללת ארבעה חלקים: סוג, תיאור, גוף וכותרת תחתונה.

ככה:

: 
[גוף אופציונלי]
[כותרת תחתונה אופציונלית]

סוּג

הסוג מתאר את סוג השינוי שנעשה בהתחייבות הנוכחית. אתה יכול להשתמש בכל מערכת הגיונית לנסיבות שלך. לדוגמה, הנה כמה מילות מפתח לדוגמה שבהן תוכל להשתמש כדי לאותת על כל סוג של שינוי, לצד שימוש לדוגמה:

• מַעֲלָל: השינויים שלך מציגים תכונה חדשה.
• לתקן: אתה מתקן באג.
• רפקטור: השינוי שלך מחזיר את הקוד מבלי לתקן באג או להוסיף תכונה חדשה.
• מִבְחָן: אתה מבצע שינויים הקשורים לבדיקות. למשל, כשאתה לכתוב מבחנים עם Jest או כל מסגרת בדיקה אחרת אתה בוחר.
instagram viewer
• עֲבוֹדָה שִׁגרָתִית: שינויים שאינם קשורים לתיקון, תכונה או בדיקה. לדוגמה, עדכון תלות.
• מסמכים: כאשר אתה מעדכן תיעוד.
• סִגְנוֹן: שינויים שאינם משפיעים על משמעות הקוד, כגון הוספת רווח לבן, חסרים נקודה-פסיק וכו'.
• perf: שינויים הקשורים לשיפורי ביצועים.
• לִבנוֹת: כאשר אתה מבצע שינויים המשפיעים על קבצי ה-build.
• ci: שינויים הקשורים לאינטגרציה מתמשכת.
• לַחֲזוֹר: בעת חזרה ל-commit קודם.

תיאור

ה"תיאור" של הודעת התחייבות הוא סיכום תמציתי ותיאורי של השינויים שנעשו בהתחייבות. היא משמשת ככותרת שתופסת את מהות ההתחייבות.

בעת כתיבת התיאור, זכור את הדברים הבאים:

• הפוך את זה ברור וספציפי מספיק כדי לתאר את ההתחייבות במבט חטוף.
• תעשה את זה קצר ותמציתי. באופן אידיאלי, הגבלתו ל-50 תווים או פחות תהיה הטובה ביותר.
• כתוב את זה בזמן הווה, גם אם אתה מתאר שינויים שכבר בוצעו.
• נצל את מצב הרוח החיווי בזמן כתיבתו.
• התחל אותו באות גדולה.
• אל תסיים את זה עם מחזור.

לדוגמה:

הישג: הטמעת החלפת מצב כהה עבור דף הבית

דוגמה זו מראה כיצד אתה יכול לכתוב את התיאור עבור commit that מיישמת מצב כהה. הוא משתמש ב- מַעֲלָל הקלד כי הוא מציג תכונה חדשה.

גוף (אופציונלי)

חלק הגוף של הודעת התחייבות מספק פרטים נוספים והקשר לגבי השינויים שבוצעו בהתחייבות. לא תמיד תזדקק לגוף, אבל הוא יכול לעזור לספק מידע נוסף, להסביר נימוק של שינוי או לתאר שיקולים טכניים כלשהם.

הנה כמה דברים שכדאי לשים לב אליהם בעת כתיבת קטע הגוף של הודעת התחייבות:

• Git אף פעם לא עוטף טקסט אוטומטית, אז עטוף אותו באופן ידני ב-72 תווים כשאתה כותב את הגוף. זה נותן ל-Git מספיק מקום להכנסת טקסט, מה שהופך אותו לקריאה יותר.
• השתמש בגוף כדי להסביר מה קרה בשינוי, מדוע ביצעת את השינוי, וההיגיון מאחורי השינוי שלך.
• עליך להשאיר שורה ריקה בין שורת התיאור לגוף. זה מאפשר ל-Git להבחין ביניהם.
• אם ההתחייבות מציגה שינויים מרובים או משפיעה על אזורים שונים של בסיס הקוד, שקול להשתמש בנקודות תבליט או בפסקאות כדי לפרק את השינויים. זה משפר את הקריאות ועוזר לקוראים להבין את ההיבטים השונים של ההתחייבות.

לדוגמה:

feat: הוסף GitHub כספק OAuth
שלב את GitHub כספק OAuth כדי לאפשר חלק 
אימות עם חשבונות GitHub.
- הטמעת זרימת אימות OAuth עם GitHub API
- הגדר את נקודות הקצה וההגדרות הנדרשות עבור אימות GitHub
- עדכן את ממשק המשתמש כך שיכלול אפשרות התחברות של GitHub

הדוגמה למעלה מציגה הודעת התחייבות טובה של Git עבור תכונה שמוסיפה GitHub כספק OAuth ליישום שלך. הודעת התחייבות זו כוללת שורת סיכום תמציתית (50 תווים או פחות), טקסט הסבר מפורט יותר (עטוף בכ-72 תווים), ונקודות תבליטים למידע נוסף.

קטע הכותרת התחתונה בהודעת התחייבות הוא חלק אופציונלי המספק מידע נוסף או מטא נתונים הקשורים להתחייבות. הוא ממוקם בדרך כלל אחרי קטע הגוף, מופרד על ידי קו ריק. הכותרת התחתונה יכולה לכלול סוגים שונים של מידע, כגון הפניות לבעיות קשורות, תגיות או הערות מיוחדות.

בעת הפניה לבעיות, בקשות משיכה או פריטים קשורים אחרים, השתמש בתחביר או בפורמט המתאימים הנדרשים על ידי מערכת מעקב הבעיות של הפרויקט שלך. זה מבטיח שההפניות מזוהות ומקושרות כהלכה.

לדוגמה:

feat: הוסף GitHub כספק OAuth
שלב את GitHub כספק OAuth כדי לאפשר חלק 
אימות עם חשבונות GitHub.
- הטמעת זרימת אימות OAuth עם GitHub API
- הגדר את נקודות הקצה וההגדרות הנדרשות עבור אימות GitHub
- עדכן את ממשק המשתמש כך שיכלול אפשרות התחברות של GitHub
פותר: #123
ראה גם: #456, #789

הכותרת התחתונה מפנה לסוגיה הקשורה מס' 123 ומציינת בעיות קשורות אחרות מס' 456 ו-#789 להקשר נוסף.

הוספת הודעת Commit

אתה יכול לכתוב הודעות commit באמצעות -M דגל ואחריו הודעת התחייבות המוקפת במרכאות (אופציונלי אך מומלץ).

ה -M הדגל הוא אידיאלי עבור הודעות commit קצרות, בדרך כלל כולל את הסוג והתיאור.

לדוגמה:

git commit -m "מטלה: שנה linter ל-ESlint"

עם זאת, כאשר הודעת ה-commit שלך דורשת יותר פרטים, כגון גוף וכותרת תחתונה, עדיף שתכתוב את ה-commit בעורך טקסט או ב-IDE.

לחלופין, אתה יכול לכתוב הודעות commit ארוכות בקובץ טקסט ולהשתמש ב- --קוֹבֶץ דגל כדי לציין את הודעות ה-commit כתוכן קובץ הטקסט.

לדוגמה:

git commit --file commit_message.txt

כאשר אתה מפעיל את הפקודה למעלה, git ישתמש בתוכן הקובץ כהודעת ה-commit.

אתה יכול גם להגיד ל-git לפתוח את עורך ברירת המחדל שלך כדי לכתוב הודעה ארוכה יותר. אם יש לך את משתני הסביבה GIT_EDITOR או EDITOR, git יפתח את התוכנית הזו כאשר אתה מפעיל קובץ חשוף git commit פקודה.

למה כדאי לכתוב הודעות מחויבות טובות

כתיבת הודעות מחויבות טובה היא חיונית לשיתוף פעולה יעיל ותחזוקת קוד. מסרים ברורים ותיאוריים מסייעים להבנה, ניפוי באגים וסקירות קוד. הם יכולים אפילו לתרום לתיעוד הפרויקט או להערות שחרור.

הם מאפשרים שיתוף ידע, כניסה חלקה ותומכים בבקרת גרסאות. תעדוף הודעות מחויבות איכותיות משפר את תהליכי הפיתוח ומבטיח תחזוקה של בסיס הקוד.