วิธีการร่วมสนับสนุน

ข้อตกลงใบอนุญาตผู้สนับสนุน (CLA)

ก่อนที่เราจะยอมรับแพตช์รหัส คุณจะต้องส่งข้อตกลงการอนุญาตให้ใช้สิทธิ (CLA) ของบุคคลหรือบริษัทอย่างใดอย่างหนึ่ง ดังนี้

  • หากคุณเป็นบุคคลธรรมดาที่เขียนโค้ดต้นฉบับ และแน่ใจว่าคุณเป็นเจ้าของทรัพย์สินทางปัญญา โปรดส่ง CLA แต่ละรายการ
  • หากทํางานให้กับบริษัท บริษัทต้องส่ง CLA ขององค์กรเพื่อระบุว่าคุณได้รับอนุญาตให้ร่วมให้ข้อมูลเกี่ยวกับงานในไลบรารีของไคลเอ็นต์นี้

ไปที่ลิงก์ใดลิงก์หนึ่งข้างต้นเพื่อเข้าถึง CLA ที่เหมาะสมและวิธีการลงนามและคืนสินค้า เมื่อได้รับแล้ว เราจะสามารถเพิ่มคุณลงใน รายชื่อผู้ร่วมเขียนข้อความอย่างเป็นทางการ

ภาพรวมของการส่งแพตช์

หากต้องการมีส่วนร่วมในโค้ดของโปรเจ็กต์นี้ ให้ทําตามขั้นตอนทั่วไปต่อไปนี้

  1. ลงนามในข้อตกลงใบอนุญาตผู้สนับสนุนตามที่อธิบายไว้ข้างต้น
  2. เข้าร่วมกลุ่มสนทนา
  3. ตั้งค่าสภาพแวดล้อมการพัฒนา
  4. เชื่อมโยงชุดการเปลี่ยนแปลงแต่ละชุดเกี่ยวกับปัญหา (รายงานข้อบกพร่องหรือคําขอฟีเจอร์) ในเครื่องมือติดตามปัญหาของ GitHub สร้างปัญหาใหม่หากยังไม่มี แล้วมอบหมายปัญหาให้ตัวเอง
  5. ดูโค้ด สร้างปัญหาใหม่ใน codereview.appspot.com และทําการตรวจสอบโค้ดให้เสร็จสิ้น ดูวิธีการโดยละเอียดสําหรับกระบวนการทั้งหมดนี้ได้ที่ด้านล่าง
  6. หลังจากโค้ดของคุณได้รับการตรวจสอบแล้วและคุณได้รับอนุมัติแล้ว ให้ยืนยันโค้ด หากคุณไม่ใช่ Contributor อย่างเป็นทางการ Contributor จะดึงชุดการเปลี่ยนแปลงของคุณไปไว้ในที่เก็บอย่างเป็นทางการ

เราใช้เครื่องมือและกระบวนการต่อไปนี้

  • เราใช้ Git เป็นระบบควบคุมเวอร์ชัน
  • เราใช้ Maven สําหรับระบบบิลด์และระบบการกระจายแบบไบนารี
  • เราใช้ codereview.appspot.com สําหรับการตรวจสอบโค้ด (แต่โปรดทราบว่าในเครื่องมือ codereview.appspot.com คําว่า "issue" หมายถึงคําขอตรวจสอบโค้ด ส่วนในเครื่องมือติดตามปัญหา GitHub; &&tt;issue" เป็นคําขอฟีเจอร์หรือรายงานข้อบกพร่อง)

หากคุณเป็นนักพัฒนาซอฟต์แวร์ 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 โดยใช้ HTTP หรือ SSH จึงจะตรวจสอบโค้ดจาก GitHub ได้ ก่อนที่จะทําตามวิธีการด้านล่าง โปรดอ่านวิธีการของ GitHub เพื่อดูวิธีเริ่มต้นใช้งานการโคลน HTTPS หรือ SSH หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับ Git โดยทั่วไป Pro Git ก็เป็นแหล่งข้อมูลที่ดี

การตรวจสอบโค้ด

การใช้ HTTPS

หากต้องการตรวจสอบที่เก็บไลบรารีในฝ่ายพัฒนา "master" ให้เรียกใช้คําสั่งต่อไปนี้

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

การใช้ SSH

หากต้องการตรวจสอบที่เก็บไลบรารีในฝ่ายพัฒนา "master" โปรดตรวจสอบว่าคุณมีสิทธิ์ในการเขียนที่เก็บ GitHub จากนั้นเรียกใช้คําสั่งต่อไปนี้

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

วิธีเปลี่ยนไปใช้สาขาอื่น เช่น 1.12

git checkout --track origin/1.12

วิธีเปลี่ยนกลับไปใช้สาขาหลัก

git checkout master

หากต้องการดึงข้อมูลการเปลี่ยนแปลงล่าสุดจากที่เก็บ GitHub และอัปเดตแผนผังการทํางานในเครื่องเป็นคอมมิตล่าสุด ให้ทําดังนี้

git pull

Maven

ติดตั้งบริการ Google Play

เมื่อตั้งค่าโปรเจ็กต์เป็นครั้งแรก คุณต้องติดตั้งไฟล์ google-play-services.jar โดยทำดังนี้

  1. เปิด Eclipse แล้วเลือก Window > 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 เมื่อทํางานกับเวอร์ชันใหม่ของไลบรารีทั้ง 3 รายการที่ยังไม่เผยแพร่ใน 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): 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

เมื่อการเปลี่ยนแปลงผ่านการทดสอบทั้งหมดแล้ว ให้เพิ่มการเปลี่ยนแปลงลงในดัชนี (พื้นที่การทดลองใช้ 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 และสร้างสาขาสําหรับฟีเจอร์ใหม่หรือแก้ไขข้อบกพร่องนี้แล้ว เมื่อคุณส่งคําขอการตรวจสอบโค้ดจากส้อมของคุณเอง โปรดตรวจสอบว่าส้อมตรงกับที่เก็บอัปสตรีมแล้ว อ่านข้อมูลเพิ่มเติมได้ที่ความช่วยเหลือในการซิงค์ส้อมของ GitHub

คุณสามารถใช้ calendar.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. สําหรับแพตช์ที่เป็นปัญหา ให้มองหา "ดาวน์โหลดข้อมูลดิบ&quot ที่มุมขวาบนของข้อกําหนดแพตช์
  3. คลิก "ข้อมูลดิบ" เพื่อรับ URL สําหรับไฟล์ที่จะนําเข้า
  4. บันทึกไฟล์ Diff ดิบลงในเครื่องในระบบโดยใช้ชื่อ เช่น 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 Tracker Tracker)

#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" ที่อยู่ด้านซ้ายบน ก่อนหน้า "Id."

กําลังยกเลิกการอัปเดตชุดการเปลี่ยนแปลง

หากมีเหตุผลที่คุณตัดสินใจที่จะไม่นําชุดข้อมูลที่คุณนําเข้าไปใช้ ให้ใช้คําสั่งต่อไปนี้เพื่อนําออก โปรดใช้ความระมัดระวัง: การลบการเปลี่ยนแปลงในระบบทั้งหมด 

git checkout -- .