שליחת שינויים בקוד

בדף הזה מתואר התהליך המלא של שליחת שינוי בקוד לפרויקט הקוד הפתוח של Android ‏ (AOSP), כולל איך לבקש בדיקה ולעקוב אחרי השינויים.

‫AOSP מסתמך על Gerrit, מערכת מבוססת-אינטרנט לבדיקת קוד בפרויקטים שמשתמשים ב-Git.

חתימה על הסכמי הרישיון של התורמים

לפני ששולחים שינויים בקוד ל-AOSP, צריך לקרוא את המאמר הסכמי רישיון וראשי תיבות של תורמים ולחתום על אחד מההסכמים הבאים:

יצירת ענף

לכל שינוי בקוד שרוצים לבצע, פועלים לפי השלבים הבאים:

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

    repo start BRANCH_NAME

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

  2. (אופציונלי) מוודאים שההסתעפות נוצרה:

    repo status .

    הענף החדש שיצרתם אמור להופיע. לדוגמה:

    project frameworks/native/                      branch mynewbranch

ביצוע השינוי ובדיקתו

כדי לבצע את השינוי ולבדוק אותו:

  1. כדי לוודא שאתם עובדים עם בסיס הקוד העדכני ביותר, מבצעים סנכרון של בסיס הקוד כולו:

    repo sync

    אם יש התנגשויות במהלך הסנכרון, כדאי לעיין בשלבים 2-4 במאמר בנושא פתרון בעיות בהתנגשויות סנכרון.

  2. מאתרים את הקוד שרוצים לשנות. כדי למצוא קוד, אפשר להשתמש בחיפוש קוד ב-Android. אתם יכולים להשתמש בחיפוש קוד של Android כדי לראות את קוד המקור של AOSP כפי שהוא מוצג כשמשתמשים בו בפועל. מידע נוסף זמין במאמר תחילת העבודה עם Code Search. כדי לראות את כל הקוד בענף הגרסה האחרון של AOSP בחיפוש הקוד של Android, עוברים אל https://cs.android.com/android/platform/superproject/.

  3. לשנות או להוסיף קבצים למקור. לכל שינוי שבוצע:

  4. איך יוצרים אפליקציות ל-Android

  5. בדיקת הגרסה

העברה של השינוי לאזור ההמתנה ושמירתו

קומִיט הוא היחידה הבסיסית של ניהול גרסאות ב-Git, והוא כולל תמונת מצב של מבנה הספריות ותוכן הקבצים של הפרויקט כולו. כדי לאשר את השינוי:

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

    git add -A

    הפקודה הזו עוקבת אחרי שינויים שביצעתם בקבצים.

  2. לוקחים את הקבצים באזור ההמתנה ומבצעים commit או מאחסנים אותם במסד הנתונים המקומי:

    git commit -s

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

  3. מזינים הודעת קומיט בפורמט הבא:

    • שורה 1: כותרת. צריך לספק סיכום של השינוי בשורה אחת (עד 50 תווים). מומלץ להשתמש בקידומות כדי לתאר את האזור ששיניתם, ואחריהן לתאר את השינוי שביצעתם בשמירה הזו. למשל, בדוגמה הבאה יש שינוי בממשק המשתמש:

      ui: Removes deprecated widget

    • שורה 2: שורה ריקה. אחרי הכותרת, מוסיפים שורה ריקה.

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

    במאמר How to Write a Git Commit Message (איך לכתוב הודעת Git Commit) אפשר לקרוא פוסט בבלוג על תיאורי Commit טובים (עם דוגמאות).

  4. שומרים את הקומיט.

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

העלאת השינוי לבדיקה

אחרי שמאשרים את השינוי בהיסטוריית ה-Git האישית, מעלים אותו ל-Gerrit:

  1. מריצים את הפקודה הבאה כדי להעלות את כל הקומיטים בכל הפרויקטים:

    repo upload

    כל השינויים בכל הפרויקטים כלולים בהעלאה.

    מוצגת הנחיה להפעיל סקריפטים של hook.

  2. מקישים על a ואז על Enter.

    תוצג לכם בקשה לאשר את ההעלאה:

    Upload project frameworks/native/ to remote branch android16-release:
branch BRANCH_NAME ( 1 commit, Wed Aug 7 09:32:33 2019 -0700):
       ff46b36d android codelab change
to https://android-review.googlesource.com/ (y/N)?

  3. מקישים על y ואז על Enter כדי לאשר את ההעלאה.

אמורה להופיע הודעה שדומה לremote: SUCCESS.

בקשת בדיקה

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

כדי לבקש בדיקה:

  1. ב-Gerrit, לוחצים על הצעת בעלים:

    הצעה לקישור בעלים ב-Gerrit

    איור 1. הצעה לקישור בעלים ב-Gerrit.

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

  2. לוחצים על בעל הקוד כדי להוסיף אותו לבדיקה.

    הכפתור שליחה מופעל.

  3. (אופציונלי) מקלידים את כתובת האימייל של כל מי שרוצים שיבדוק את השינוי.

  4. לוחצים על שליחה כדי לשלוח את השינוי לבדיקה.

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

קביעת סטטוס השינוי

כדי לראות את הסטטוס של הקבצים בשינוי, בודקים אם מופיעים הסמלים הבאים ליד הקבצים בשינוי:

  • (סמל וי): אושר על ידי בעל הקוד
  • (סמל הצלב): לא אושר על ידי בעל הקוד
  • ‫ (סמל השעון ): בהמתנה לאישור של בעל הקוד

באיור הבא אפשר לראות את סמלי הסטטוס האלה שמופיעים לצד קבצים בשינוי:

דוגמה לקבצים עם סמלים שמציגים אישור של בעלי הקוד

איור 2. דוגמה לקבצים עם סמלים שמציגים אישור של בעלי הקוד.

תיקון המשוב והעלאה של שינוי חלופי

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

כדי לפתור את הבעיה שצוינה במשוב ולשנות את השינוי:

  1. פועלים לפי שלבים 2-4 בקטע ביצוע השינוי ובדיקתו.

  2. מריצים את הפקודות הבאות כדי לתקן את השינוי:

    git add -A
git commit --amend

  3. מעלים את השינוי.

כשמעלים את השינוי המתוקן, הוא מחליף את השינוי המקורי גם ב-Gerrit וגם בהיסטוריית ה-Git המקומית.

פתרון בעיות שקשורות לסנכרון

אם שינויים אחרים נשלחים לעץ המקור ומתנגשים עם השינויים שלכם, תקבלו הודעה שיש התנגשויות. כדי לפתור את העריכות המתנגשות:

  1. ודאו שאתם עובדים עם הקוד העדכני ביותר:

    repo sync .

    הפקודה repo sync מאחזרת את העדכונים משרת המקור, ואז מנסה לבצע באופן אוטומטי rebase של HEAD על HEAD המרוחק החדש.

  2. אם המיזוג האוטומטי לא מצליח, צריך לבצע מיזוג ידני:

    repo rebase .

  3. פתרון קונפליקטים במיזוג. אם אין לכם שיטה מועדפת לפתרון בעיות שנובעות ממיזוג, אתם יכולים להשתמש ב-git mergetool כדי לפתור ידנית בעיות שנובעות ממיזוג בין קבצים.

  4. אחרי שמתקנים את הקבצים שגורמים לקונפליקט, מריצים את הפקודה הבאה כדי להחיל את הקומיטים החדשים:

    git rebase --continue

שליחת השינוי

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

אחרי שהשליחה שלכם תמוזג, תוכלו להיכנס ללוח הבקרה של Android Continuous Integration כדי לעקוב אחרי השילוב של השליחות שלכם בעץ.