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

בדף הזה מתואר התהליך המלא לשליחת שינוי קוד לפרויקט Android Open Source Project‏ (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 Code Search. אתם יכולים להשתמש בחיפוש הקוד של Android כדי להציג את קוד המקור של AOSP כפי שהוא מוצג כשאתם משתמשים בו בפועל. מידע נוסף זמין במאמר תחילת העבודה עם חיפוש קוד. כדי להציג את כל הקוד בהסתעפות main בחיפוש הקוד של Android, עוברים אל https://cs.android.com/android/platform/superproject/main.

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

  4. פיתוח Android.

  5. בודקים את ה-build.

שלב ושמירה של השינוי

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

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

    git add -A

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

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

    git commit -s

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

  3. כותבים הודעת השמירה בפורמט הבא:

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

      ui: Removes deprecated widget

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

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

    בפוסט בבלוג איך כותבים הודעות commit ב-Git מוסבר איך לכתוב תיאורים טובים של השינויים (עם דוגמאות).

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

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

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

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

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

    repo upload

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

    תתבקשו להריץ סקריפטים של הוק.

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

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

    Upload project frameworks/native/ to remote branch main:
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, לוחצים על SUGGEST OWNERS:

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

    איור 1. הקישור Suggest owners ב-Gerrit.

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

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

    הלחצן שליחה מופעל.

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

  4. (אופציונלי) לוחצים על +1 לצד 'שליחת בקשה אוטומטית' כדי לשלוח את השינוי באופן אוטומטי אחרי שתקבלו אישורים. אם לא תלחצו על הלחצן הזה, עובד Google יצטרך לשלוח את השינוי בשבילכם.

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

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

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

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

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

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

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

איור 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

שליחת השינוי

אחרי שהבקשה עוברת את תהליך הבדיקה והאימות, בודק של Google צריך לשלוח את הקוד בשבילכם. משתמשים אחרים יכולים להריץ את הפקודה repo sync כדי למשוך את העדכון ללקוחות המקומיים שלהם.

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