איך מוסיפים תוכן?

הסכמי רישיון לתורמים (CLA)

כדי שנוכל לקבל את תיקוני הקוד, עליכם להגיש הסכם רישיון פרטי או ארגוני לתורמים (CLA):

  • אם אתם אנשים שכותבים קוד מקור מקורי ואתם בטוחים שאתם הבעלים של הקניין הרוחני, הגישו הסכם רישיון נפרד.
  • אם אתם עובדים בחברה, החברה שלכם חייבת לשלוח הסכם רישיון עסק (CLA) כדי לציין שאתם רשאים לתרום את העבודה שלכם לספריית הלקוח הזו.

תוכלו להשתמש באחד משני הקישורים שלמעלה כדי לגשת לתנאי הסכם רישיון התוכן (CLA) ולהוראות לגבי החתימה וההחזרה שלו. אחרי שנקבל אותו, נוכל להוסיף אתכם לרשימה הרשמית של תורמי התוכן.

סקירה כללית של שליחת תיקונים

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

  1. חותמים על הסכם רישיון לתורמים, כפי שמתואר למעלה.
  2. הצטרפו לקבוצת הדיון שלנו.
  3. מגדירים את סביבת הפיתוח.
  4. משייכים כל אחת מקבוצות השינויים שלכם לבעיה (דוח איתור באגים או בקשה להוספת תכונה) במאתר הבעיות של GitHub. יוצרים בעיה חדשה, אם אין עדיין בעיה ומקצים אותה לעצמכם.
  5. בודקים את הקוד, יוצרים בעיה חדשה בכתובת codereview.appspot.com ומשלימים את תהליך בדיקת הקוד. הוראות מפורטות לכל התהליכים האלה מופיעות בהמשך.
  6. אחרי שהקוד שלכם נבדק וקיבלת אישור, צריך לשמור את הקוד. אם אתם לא 'תורמים' רשמיים, 'תורם' יכניס את השינוי שלכם למאגר הרשמי.

אנחנו משתמשים בכלים ובתהליכים הבאים:

  • אנחנו משתמשים ב-Git בתור המערכת שלנו לניהול גרסאות.
  • אנחנו משתמשים ב-Maven למערכת ה-build וגם במערכת הפצה בינארית.
  • אנחנו משתמשים ב-codereview.appspot.com לבדיקות קוד. (אבל שימו לב שבכלי codereview.appspot.com, המונח "בעיה" פירושו בקשה לבדיקת הקוד, ואילו "בעיה" היא בקשת תכונה או דוח על באג.

אם אתם מפתחי Eclipse, אתם צריכים להשתמש בפורמט הקוד הספציפי לפרויקט שצוין בספרייה .settings, שמעובד באופן אוטומטי על ידי Eclipse.

הגדרת סביבת הפיתוח

דרישות מוקדמות

  1. מתקינים את Java 6. יכול להיות שתצטרכו להגדיר את המשתנה JAVA_HOME.
  2. מתקינים את Maven. (המסמך הזה מבוסס על היכרות בסיסית עם פקודות Maven.)
  3. אופציונלי: מתקינים את Android SDK ומגדירים את המשתנה Android_Home כמיקום ההתקנה של Android.
  4. מתקינים את Git.

הגדרת Git

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

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS"

אימות באמצעות GitHub מ-Git

כדי שתוכלו לבדוק את הקוד מ-GitHub, אתם צריכים לבצע אימות ב-GitHub באמצעות HTTP או SSH. לפני שממשיכים בהוראות שכאן, קראו את instructions של GitHub כדי ללמוד איך להתחיל לעבוד עם שכפול HTTPS או SSH. אם תרצו לקבל מידע נוסף על Git באופן כללי, מומלץ להיעזר ב-Pro Git.

בדיקת הקוד

שימוש ב-HTTPS

כדי לבדוק את מאגר הספרייה בהסתעפות "master" של הפיתוח, מריצים את הפקודה הבאה:

git clone https://github.com/google/google-api-java-client.git

שימוש ב-SSH

כדי לבדוק את מאגר הספריות בהסתעפות ה "מאסטר" של הפיתוח, ודאו שיש לכם גישת כתיבה למאגר של GitHub ואז מריצים את הפקודה הבאה:

git clone git@github.com:google/google-api-java-client.git

כדי לעבור להסתעפות חלופית, לדוגמה 1.12:

git checkout --track origin/1.12

כדי לחזור להסתעפות הראשית:

git checkout master

כדי לשלוף את השינויים האחרונים ממאגר הנתונים ב-GitHub ולעדכן את עץ העבודה המקומי ל-Committ האחרונה:

git pull

מייבן

התקנת Google Play Services

בפעם הראשונה שמגדירים את הפרויקט, צריך להתקין את הקובץ google-play-services.jar. לשם כך:

  1. מפעילים את Eclipse ובוחרים באפשרות Window > Android SDK Manager, או הריצו את android בשורת הפקודה.
  2. גוללים לתחתית רשימת החבילות ובוחרים Extras > Google Play Services.
mvn install:install-file \
           -Dfile=$ANDROID_HOME/extras/google/google_play_services/libproject/google-play-services_lib/libs/google-play-services.jar \
           -DgroupId=com.google.android.google-play-services \
           -DartifactId=google-play-services \
           -Dversion=1 \
           -Dpackaging=jar

הידור הפרויקט

mvn clean install

Maven מתקינה את הקבצים הבינאריים המהודרים למאגר מקומי (לדוגמה ~/.m2/repository). הוא מחפש קבצים בינאריים במאגר הזה לפני האחזור מהמאגר המרכזי של Maven.

הערה: הספרייה הזו תלויה ב-google-http-java-client וב-google-oauth-java-client. כשעובדים על גרסה חדשה של כל שלוש הספריות שעדיין לא שוחררו למרכז Maven, צריך להדר אותן בסדר הבא:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client סידור לפי הסדר הזה מבטיח ש-Maven יאסוף את הקבצים הבינאריים ההדורים כדי ליצור אוסף של ספריות תלויות.

תהליך בדיקת הקוד

הורדת הסקריפט upload.py

מורידים את הסקריפט upload.py ואפשר גם להוסיף אותו ל-Path שלכם.

בפעם הראשונה שמריצים את upload.py, תתבקשו להזין סיסמה ספציפית לאפליקציה:

Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com
Password for your_email_address@yourdomain.com:

הכנת הקוד שלך לבדיקה

לפני ששולחים את הקוד לבדיקה, צריך להריץ את Clirr כדי לזהות בעיות תאימות לאחור בקוד. אם מדווחות שגיאות, צריך לתקן אותן או לעדכן את הקובץ clirr-ignored-differences.xml.

mvn -q clirr:check

אתם חייבים גם להריץ את הכלי FindBugs כדי לאתר באגים בקוד. אם מדווחות שגיאות, צריך לתקן אותן או לעדכן את הקובץ findbugs-exclude.xml. (שימו לב ש-FindBugs פועל באיטיות רבה).

mvn findbugs:check

אחרי שהשינוי יעבור את כל הבדיקות, צריך להוסיף אותו לאינדקס (אזור ה-Staging של Git):

git add .

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

git status

בפלט git status, בודקים את הקטע שנקרא 'השינויים שיבוצעו בקרוב'.

בדיקת הקוד מתחילה

כשמוכנים לבדיקה, יש ליצור בעיה חדשה בכתובת codereview.appspot.com: 

upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

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

upload.py --rev=HEAD -i 123456

להצגת אפשרויות נוספות, הריצו את upload.py --help.

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

כמו כן, ניתן להשתמש ב-upload.py: שינויים במערכי שינויים מקומיים.

upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

בודק הקוד

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

ייבוא קבוצת שינויים

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

כדי לשלוף ולמזג את ההתחייבויות האחרונות מהמאגר המרוחק:

git pull

כדי לבדוק מה מופיע בעץ ובאינדקס הפעילים:

git status

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

  1. פותחים את הבעיה בכתובת codereview.appspot.com.
  2. לתיקון הרלוונטי, חפשו את הכיתוב Download RAW בפינה הימנית העליונה של מפרט התיקון.
  3. כדי לקבל כתובת URL לייבוא של הקובץ, לוחצים על 'Raw'.
  4. שומרים את קובץ המקור הגולמי במחשב המקומי בשם כמו issue123456.diff.
  5. עוברים לעץ העבודה המקומי של Git ומחילים את ההפרש באמצעות הפקודה patch:
patch -p1 < issue123456.diff

כדי לוודא שייבאתם את ההפרש הנכון, כדאי לבצע git diff בעץ העבודה.

בדיקת מערך השינויים

כדי להריץ את הבדיקות ולהתקין, משתמשים בפקודה הבאה:

mvn clean install checkstyle:check

אישור קבוצת שינויים בכתובת codereview.appspot.com

באופן כללי, אי אפשר לדחוף קוד למאגר GitHub עד שבודק הקוד מחליט שהקוד מוכן. בשלב הזה, המוסכמה היא להגיב עם ההודעה "LGTM" (נראה טוב לי).

הפעלת הקוד

חשוב: לפני שמחילים את הקוד, צריך להביא את השינויים האחרונים לעץ העבודה ולעדכן את עץ העבודה ל-Commit ממאגר GitHub:

git pull

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

כדי להחיל את הקוד באופן מקומי: 

git commit

מזינים את ההודעה הבאה (בהנחה שמתקנים או מטמיעים את בעיה מס' 123, כפי שמפורט במעקב אחר בעיות של GitHub):

#123: NullPointerException when passing null to processFoo()
http://codereview.appspot.com/123456/

לפני הנקודתיים הראשונה והתיאור:

  • אם זהו תיקון לבעיה במעקב אחר בעיות, יש לציין את מספר הבעיה כפי שמוצג.
  • אם מדובר בשינוי לסניף מסוים, יש לציין את מספר הסניף.
  • אתה תהיה הcommitter של התחייבות זו, אך תן קרדיט למחבר השינוי על ידי סימון שלו בתור author (--author=<author>).

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

כדי לדחוף את השינוי למאגר של GitHub:

git push

אם במהלך git push מופיעה הודעת שגיאה על דחיית עדכונים (אולי שכחתם להפעיל את git pull), כך מתמזגים עם השינויים האחרונים ומעבירים את השינויים למאגר המרוחק: 

git pull
git commit
git push

סגירת הבעיה

צריך לסגור את הבעיה בכלי לבדיקת הקוד. לשם כך:

  1. בוחרים את הבעיה באתר codereview.appspot.com.
  2. לוחצים על ה-X שבפינה הימנית העליונה, לפני הכיתוב ID.

תיקון ערכת שינויים

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

git checkout -- .