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

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

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

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

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

התחלת הסתעפות

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

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

    repo start BRANCH_NAME

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

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

    repo status .

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

    project frameworks/native/                      branch mynewbranch

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

כך מבצעים שינויים ובודקים אותם:

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

    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.

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

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

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

    git add -A

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

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

    git commit -s

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

  3. צריך לספק הודעת שמירה בפורמט הבא:

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

      ui: Removes deprecated widget

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

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

    כדי לקרוא בלוג על תיאורים טובים של התחייבות (עם דוגמאות), ראו איך לכתוב הודעה של Git Commit.

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

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

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

לאחר ביצוע השינוי בהיסטוריית ה-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, לוחצים על בעלים מוצעים:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כדי לטפל במשוב ולתקן את השינוי:

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

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

    git add -A
git commit --amend

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

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

פתרון התנגשויות סנכרון

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

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

    repo sync .

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

  2. אם ה-rebase האוטומטי נכשל, מבצעים rebase ידני:

    repo rebase .

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

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

    git rebase --continue

שליחת השינוי

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

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