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

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

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

  4. פיתוח Android.

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

שלב וביצוע השינוי

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

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

    git add -A

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

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

    git commit -s

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

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

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

      ui: Removes deprecated widget

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

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

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

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

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

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

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

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

    repo upload

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

    תוצג בקשה להריץ סקריפטים של הוק (hook).

  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 כדי לעקוב אחרי השילוב של הקוד שלכם בעץ.