הסכמי רישיון לתורמים (CLA)
כדי שנוכל לקבל את תיקוני הקוד, עליכם להגיש הסכם רישיון פרטי או ארגוני לתורמים (CLA):
- אם אתם אנשים שכותבים קוד מקור מקורי ואתם בטוחים שאתם הבעלים של הקניין הרוחני, הגישו הסכם רישיון נפרד.
- אם אתם עובדים בחברה, החברה שלכם חייבת לשלוח הסכם רישיון עסק (CLA) כדי לציין שאתם רשאים לתרום את העבודה שלכם לספריית הלקוח הזו.
תוכלו להשתמש באחד משני הקישורים שלמעלה כדי לגשת לתנאי הסכם רישיון התוכן (CLA) ולהוראות לגבי החתימה וההחזרה שלו. אחרי שנקבל אותו, נוכל להוסיף אתכם לרשימה הרשמית של תורמי התוכן.
סקירה כללית של שליחת תיקונים
כדי לתרום קוד לפרויקט הזה, מבצעים את השלבים הכלליים הבאים:
- חותמים על הסכם רישיון לתורמים, כפי שמתואר למעלה.
- הצטרפו לקבוצת הדיון שלנו.
- מגדירים את סביבת הפיתוח.
- משייכים כל אחת מקבוצות השינויים שלכם לבעיה (דוח איתור באגים או בקשה להוספת תכונה) במאתר הבעיות של GitHub. יוצרים בעיה חדשה, אם אין עדיין בעיה ומקצים אותה לעצמכם.
- בודקים את הקוד, יוצרים בעיה חדשה בכתובת codereview.appspot.com ומשלימים את תהליך בדיקת הקוד. הוראות מפורטות לכל התהליכים האלה מופיעות בהמשך.
- אחרי שהקוד שלכם נבדק וקיבלת אישור, צריך לשמור את הקוד. אם אתם לא 'תורמים' רשמיים, 'תורם' יכניס את השינוי שלכם למאגר הרשמי.
אנחנו משתמשים בכלים ובתהליכים הבאים:
- אנחנו משתמשים ב-Git בתור המערכת שלנו לניהול גרסאות.
- אנחנו משתמשים ב-Maven למערכת ה-build וגם במערכת הפצה בינארית.
- אנחנו משתמשים ב-codereview.appspot.com לבדיקות קוד. (אבל שימו לב שבכלי codereview.appspot.com, המונח "בעיה" פירושו בקשה לבדיקת הקוד, ואילו "בעיה" היא בקשת תכונה או דוח על באג.
אם אתם מפתחי Eclipse, אתם צריכים להשתמש בפורמט הקוד הספציפי לפרויקט שצוין בספרייה .settings, שמעובד באופן אוטומטי על ידי Eclipse.
הגדרת סביבת הפיתוח
דרישות מוקדמות
- מתקינים את Java 6. יכול להיות שתצטרכו להגדיר את המשתנה
JAVA_HOME
. - מתקינים את Maven. (המסמך הזה מבוסס על היכרות בסיסית עם פקודות Maven.)
- אופציונלי: מתקינים את Android SDK ומגדירים את המשתנה Android_Home כמיקום ההתקנה של Android.
- מתקינים את 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. לשם כך:
- מפעילים את Eclipse ובוחרים באפשרות Window > Android SDK Manager, או הריצו את
android
בשורת הפקודה. - גוללים לתחתית רשימת החבילות ובוחרים 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, צריך להדר אותן בסדר הבא:
- google-http-java-client
- google-oauth-java-client
- 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:
- פותחים את הבעיה בכתובת codereview.appspot.com.
- לתיקון הרלוונטי, חפשו את הכיתוב Download RAW בפינה הימנית העליונה של מפרט התיקון.
- כדי לקבל כתובת URL לייבוא של הקובץ, לוחצים על 'Raw'.
- שומרים את קובץ המקור הגולמי במחשב המקומי בשם כמו issue123456.diff.
- עוברים לעץ העבודה המקומי של 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
סגירת הבעיה
צריך לסגור את הבעיה בכלי לבדיקת הקוד. לשם כך:
- בוחרים את הבעיה באתר codereview.appspot.com.
- לוחצים על ה-X שבפינה הימנית העליונה, לפני הכיתוב ID.
תיקון ערכת שינויים
אם מסיבה כלשהי אינכם רוצים לבצע שינויים שייבאתם, השתמשו בפקודה הבאה כדי להסיר אותה. זהירות: כל השינויים המקומיים נמחקים באופן מילולי.
git checkout -- .