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

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

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

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

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

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

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

   • לקוד Java, פועלים לפי סגנון קוד AOSP Java לתורמים.

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

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

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

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

   

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

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

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

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

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

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

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

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

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

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

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

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

איור 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 כדי לשלוף את העדכון אל המכשיר המקומי שלהם הלקוחות שלנו.

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