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

ข้อตกลงการอนุญาตให้ใช้สิทธิผู้สนับสนุน (CLA)

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

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

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

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

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

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

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

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

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

กำลังตรวจสอบโค้ด

การใช้ HTTPS

เพื่อตรวจสอบที่เก็บไลบรารีใน "ต้นแบบ" สำหรับการพัฒนาซอฟต์แวร์ สาขา เรียกใช้คำสั่งต่อไปนี้

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

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

git checkout master

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

git pull

Maven

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

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

  1. เปิด Eclipse และเลือกหน้าต่าง > 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 และสร้าง Branch สำหรับฟีเจอร์ใหม่หรือแก้ไขข้อบกพร่องนี้แล้ว เมื่อคุณ ส่งรหัส ตรวจสอบคำขอจากส้อมของคุณเอง ตรวจสอบว่าส้อมของคุณซิงค์กับ ที่เก็บอัปสตรีม ดูข้อมูลเพิ่มเติมได้จากความช่วยเหลือของ 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. สำหรับแพตช์ที่มีปัญหา ให้มองหา "ดาวน์โหลดข้อมูลดิบ" ที่ด้านขวาบนของส่วน ข้อกำหนดแพตช์
  3. คลิก "ข้อมูลดิบ" เพื่อรับ URL สำหรับไฟล์ที่จะนำเข้า
  4. บันทึกไฟล์ความแตกต่างแบบ Raw ไปยังเครื่องของคุณพร้อมชื่อ เช่น issue123456.diff
  5. ไปที่แผนผังการทำงานของ Git ในเครื่องและใช้ความแตกต่างโดยใช้ patch คำสั่ง:
patch -p1 < issue123456.diff

หากต้องการตรวจสอบอีกครั้งว่าคุณนำเข้าความแตกต่างที่ถูกต้อง ให้ทำ git diff ในแผนผังการทำงาน

การทดสอบชุดการเปลี่ยนแปลง

หากต้องการเรียกใช้การทดสอบและติดตั้ง ให้ใช้คำสั่งต่อไปนี้

mvn clean install checkstyle:check

การอนุมัติ Changeset บน 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 -- .