Committing policies/he
הרתמות
יצירת דיווח תקל, בקשת תכונה או GEP
- מומלץ שכל שינוי ילווה בדיווח תקל, בבקשת תכונה חדשה או ב־GEP (Gramps Enhancement Proposal).
- תיקון תקל מתוך דיווח תקל קיים הוא דרך טובה להתחיל פיתוח בגרמפס.
דיון בשינוי ברשימת התפוצה
- מאפשר הגעה להסכמה בין כל המפתחים על תכנון ראוי שעולה בקנה אחד עם מדיניות המפתחים.
- חשוב עבור תכונות חדשות ושינויים במנשק המשתמש.
- אינו נחוץ לשינויים קטנים, או כאשר התקיים דיון מספק בדיווח התקל.
- הסכמה על תכנון לפני כתיבת קוד עשויה למנוע השקעת זמן בקידוד לשווא.
- אם השינוי גדול, עשויה לעלות דרישה לכתיבת GEP.
יישום השינוי בקוד
- יש להקצות (assign) את דיווח התקל או את בקשת התכונה לעצמכם.
- אם מתאים, יש להוסיף את השינוי ל־Roadmap.
- עבור שינויים גדולים יש ליצור ענף GEP.
יצירת בקשת משיכה (Pull Request)
- אלא אם מדובר בשינוי זניח, יש ליצור Pull Request (PR) כדי לאפשר סקירת קוד.
- יש להוסיף לעוקב התקלים קישור ל־PR. יש להשתמש בתחביר p:gramps:nnn: כאשר nnn הוא מספר ה־PR.
- יש לבצע rebase ל־PR באופן סדיר על הענף העילי (upstream). אין למזג ענפים לתוך ה־PR.
ענפים
- תכונות חדשות יש להתחייב (commit) לענף master.
- תיקוני תקלים בלבד יש להתחייב לענפי תחזוקה (maintenance branches).
- את ענף התחזוקה הנוכחי יש למזג באופן סדיר אל ענף master.
- תרגומים אפשר להתחייב לענף gramps60. בגרסאות מאוחרות יותר נעשה שימוש ב־Weblate, ואין לערוך קובצי po ישירות.
מיזוג
- את רוב השינויים יש למזג באמצעות squash ובאופן fast-forward.
- תכונות חדשות גדולות יש למזג no-ff כדי לשמור על זהות תהליך הפיתוח.
- עיקרון זה חל הן על Pull Requests והן על עבודה של מפתחים בעלי הרשאת כתיבה למאגר.
בקשות משיכה (Pull Request)
- בקשות משיכה (Pull Request) חייבים לעבור סקירת קוד ובדיקה בידי מפתח.
- אין להניח שמחברי PR הם מומחי Git, ולכן באחריות המפתח שמבצע את המיזוג לוודא שה־PR נקי ושאינו “מלכלך” את היסטוריית המאגר.
- לחצן GitHub “Squash and merge” יכול לשמש עבור רוב השינויים הקטנים.
- מיזוג no-ff מחוץ ל־GitHub עדיף כאשר יש תועלת בשימור היסטוריית ההתחייבויות.
- תיקוני תקלים חייבים להיות מחויבים לענף היציב הנוכחי.
- רק תכונות חדשות יש להתחייב ישירות ל־master.
הודעות יומן
כל התחייבות ל־Git חייבת לכלול הודעת יומן. הודעות אלו ייכללו ב־ChangeLog בעת יצירת גרסה, ועליהן לעמוד בהנחיות הבאות:
תקציר
- השורה הראשונה של הודעת ההתחייבות צריכה להיות תקציר קצר של השינוי.
- לכל היותר 70 תווים.
תיאור
- את התיאור יש להפריד מן התקציר באמצעות שורה ריקה אחת.
- יש לתאר, ככל האפשר, כיצד השינוי משפיע על התפקוד מנקודת המבט של המשתמש.
- מומלץ להשתמש במשפטים שלמים.
- אין צורך לתאר פרטים זעירים של השינוי או לציין אילו קבצים הושפעו, משום שמידע זה כבר נשמר ב־Git ואפשר לצפות בו באמצעות
git diff. - בעת התחייבות של קוד שהתקבל כתִרומה, יש לתת קרדיט למחבר באמצעות האפשרות
--author. - אם יש צורך להפנות להתחייבות אחרת, יש להשתמש ב־commit hash המלא. מנשק הרשת של GitHub יהפוך אותו לקישור באופן אוטומטי. הערה: hash בן 6 ספרות הקסדצימליות שמופיע בסוגריים מרובעים [ ] לא יעבוד עם קישור אוטומטי ב־GitHub.
שילוב עם מעקב התקלים
אפשר להשתמש במילות מפתח מיוחדות כדי לקשר לדיווחי תקל, או כדי לסגור אותם. יש להציב אותן בשורה האחרונה של הודעת ההתחייבות, ולהפריד משאר ההודעה באמצעות שורה ריקה אחת.
כדי לפתור תקל/תקלים יש להשתמש ב־:
- Fixes #12345
- Fixed #12345
- Resolves #12345
- Resolved #12345
- Fixes #12345, #67890
- Fixed #12345, #67890
- Resolves #12345, #67890
- Resolved #12345, #67890
כדי לקשר לתקל/תקלים (ללא פתרון) יש להשתמש ב־:
- Bug #12345
- Issue #12345
- Report #12345
- Bugs #12345, #67890
- Issues #12345, #67890
- Reports #12345, #67890
כדי שמנגנון זה יעבוד, המחבר או המתחייב (committer) צריכים להיות מפתחים בעוקב התקלים של Mantis. השם ב־Git צריך להתאים לשם המשתמש או לשם האמיתי ב־Mantis, או לחלופין כתובת הדוא״ל ב־Git צריכה להתאים לכתובת הדוא״ל ב־Mantis.
פקודות שימושיות
אפשר לראות את השינויים האחרונים באמצעות הפקודה git log, לדוגמה:
git log --oneline
אפשר גם להגביל את מספר הרשומות שמוצגות באמצעות הדגל -n. הוספת --stat מציגה אילו קבצים הושפעו מן ההתחייבות:
git log -5
כדי לתת קרדיט לתורם של טלאי (patch), יש להשתמש ב־:
git commit --author='A U Thor <[email protected]>'
הוספת קבצים חדשים
כל הקבצים שכוללים מחרוזות לתרגום חייבים להופיע בקבצים po/POTFILES.in או po/POTFILES.skip. משמעות הדבר היא שברוב המקרים יש להוסיף את שם הקובץ החדש לרשימות אלו.
יש לזכור לעשות זאת עבור כל קובץ חדש שמתווסף ל־Git.
בדיקה
אפשר לבצע בדיקה בעותק מקומי באמצעות:
PYTHONPATH=../../gramps python po/test/po_test.py
כאשר ../.. הוא הנתיב לעותק המקומי.
הסרת קבצים
יש לזכור להסיר הפניות לקובץ מן הקבצים po/POTFILES.in ו־po/POTFILES.skip.
למידע נוסף
((RTLPageEand))