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

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

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

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

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

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

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

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

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

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

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

בדיקת הקוד מתבצעת...

שימוש ב-HTTPS

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

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

שימוש ב-SSH

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

git clone [e-mail]:google/google-api-java-client.git

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

git checkout --track origin/1.12

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

git checkout master

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

git pull

Maven

התקנת Google Play Services

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

1. מפעילים את ליקוי חמה ובוחרים חלון > Android SDK Manager, או להריץ את android בשורת הפקודה.
2. גוללים לחלק התחתון של רשימת החבילות ובוחרים באפשרות תוספות > Google Play שירותים שונים.

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 Central, צריך להדר אותם בסדר הבא:

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): [e-mail]
Password for [e-mail]: 

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

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

mvn -q clirr:check

בנוסף, עליכם להפעיל את הכלי FindBugs כדי לאתר באגים בקוד. אם יש שגיאות מדווחים, עליך לתקן אותם או לעדכן את findbugs-exclusion.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 ...

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

אחרי ביצוע שינויים נוספים, מעבירים את השינויים החדשים לשלב הדרגתי. כדי להעלות תיקון חדש: לדוגמה, להנפקה של מספר 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. עבור התיקון הרלוונטי, מחפשים את האפשרות 'הורדת RAW' בפינה הימנית העליונה של מפרט תיקון.
3. לוחצים על 'גולמי' כדי לקבל את כתובת ה-URL של הקובץ לייבוא.
4. שומרים את קובץ ההבדלים הגולמיים במחשב המקומי בשם כמו issue123456.diff.
5. נכנסים לעץ העבודה המקומי של Git ומחילים את ההבדל באמצעות patch הפקודה:

patch -p1 < issue123456.diff

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

בדיקת קבוצת השינויים

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

mvn clean install checkstyle:check

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

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

שליחת הקוד מתבצעת

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

git pull

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

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

git commit

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

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

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

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

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

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

git push

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

git pull
git commit
git push

סגירת הבעיה

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

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

ביטול תיקון של קבוצת שינויים

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

git checkout -- .