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

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

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

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

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

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

ในการร่วมให้โค้ดในโครงการนี้ ให้ทำตามขั้นตอนทั่วไปต่อไปนี้:

  1. ลงนามในข้อตกลงใบอนุญาตผู้สนับสนุนตามที่อธิบายไว้ข้างต้น
  2. เข้าร่วมกลุ่มสนทนาของเรา
  3. ตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์
  4. เชื่อมโยงชุดการเปลี่ยนแปลงแต่ละรายการกับปัญหา (รายงานข้อบกพร่องหรือคำขอฟีเจอร์) ในเครื่องมือติดตามปัญหาของ 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 โดยใช้ HTTP หรือ SSH จึงจะตรวจสอบโค้ดจาก GitHub ได้ โปรดอ่านinstructionsของ 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 และเพิ่มลงในเส้นทางของคุณ (ไม่บังคับ)

ครั้งแรกที่คุณเรียกใช้ 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 เกี่ยวกับวิธีซิงค์ส้อม

คุณสามารถใช้ 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. คลิก "raw" เพื่อดู 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>)

ตามคำอธิบาย ให้ใส่ลิงก์ไปยังปัญหาในเว็บไซต์ Codereview เสมอ ลิงก์นี้สำคัญเพราะหากไม่มีลิงก์ดังกล่าว ก็จะไม่มีวิธีที่สะดวกในการระบุการตรวจสอบโค้ดที่เกี่ยวข้องกับคอมมิต ซึ่งมีประโยชน์ในการคงประวัติการสนทนาไว้

วิธีพุชการเปลี่ยนแปลงไปยังที่เก็บ GitHub

git push

หากได้รับข้อความแสดงข้อผิดพลาดเกี่ยวกับการปฏิเสธการอัปเดตในช่วง git push (คุณอาจลืมเรียกใช้ git pull) ต่อไปนี้คือวิธีผสานรวมการเปลี่ยนแปลงล่าสุดและส่งการเปลี่ยนแปลงไปยังที่เก็บระยะไกล 

git pull
git commit
git push

กำลังปิดปัญหา

โปรดปิดปัญหาในเครื่องมือตรวจสอบโค้ด โดยทำดังนี้

  1. เลือกปัญหาใน codereview.appspot.com
  2. คลิก "X" ที่ด้านซ้ายบน นำหน้า "Id" (รหัส)

การยกเลิกการแพตช์ชุดการเปลี่ยนแปลง

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

git checkout -- .