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

בדף הזה מתואר התהליך המלא של שליחת שינוי בקוד לפרויקט הקוד הפתוח של 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. לשנות או להוסיף קבצים למקור. לכל שינוי שבוצע:

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

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

   • במקרה של קוד Java, צריך לפעול לפי סגנון קוד Java של AOSP לתורמי קוד.

   • חלקים מסוימים ב-AOSP כתובים ב-Kotlin (.kt), ואפשר להשתמש ב-Kotlin באזורים בפלטפורמה שכבר כתובים ב-Kotlin. מידע נוסף על Kotlin ב-Android זמין במדריך הסגנון של Kotlin ובמדריך לאינטראופרביליות של Kotlin-Java למפתחי Android. הנחיות מקיפות יותר לגבי Kotlin זמינות באתר השפה של Kotlin.

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

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 android17-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, לוחצים על SUGGEST OWNERS:

   

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

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

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

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

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

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

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

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

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

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

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

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