Cách đóng góp

Thỏa thuận cấp phép cộng tác viên (CLA)

Trước khi chúng tôi có thể chấp nhận các bản vá mã của bạn, bạn cần gửi cá nhân hoặc Thỏa thuận cấp phép cộng tác viên (CLA):

  • Nếu bạn là một cá nhân viết mã nguồn gốc và chắc chắn rằng mình sở hữu tài sản trí tuệ đó, hãy gửi một CLA riêng lẻ.
  • Nếu bạn làm việc cho một công ty, công ty của bạn phải gửi CLA công ty để cho biết rằng bạn được phép đóng góp công việc cho thư viện khách hàng này.

Truy cập một trong hai đường liên kết ở trên để truy cập vào CLA thích hợp và hướng dẫn cách ký và trả lại CLA. Sau khi nhận được thông báo, chúng tôi có thể thêm bạn vào danh sách cộng tác viên chính thức.

Tổng quan về cách gửi bản vá

Để đóng góp mã cho dự án này, hãy làm theo các bước chung sau:

  1. Ký Thoả thuận cấp phép cộng tác viên, như mô tả ở trên.
  2. Tham gia nhóm thảo luận của chúng tôi.
  3. Thiết lập môi trường phát triển của bạn.
  4. Liên kết từng thay đổi của bạn với một Vấn đề (báo cáo lỗi hoặc yêu cầu về tính năng) trong Công cụ theo dõi lỗi của GitHub của chúng tôi. Hãy tạo Vấn đề mới nếu chưa có vấn đề và tự chỉ định cho mình.
  5. Hãy xem mã, tạo một vấn đề mới trên codereview.appspot.com và hoàn tất quy trình xem xét mã. Dưới đây là hướng dẫn chi tiết về tất cả các quy trình này.
  6. Sau khi mã của bạn được xem xét và bạn nhận được chấp thuận, hãy xác nhận mã. Nếu bạn không phải là một Cộng tác viên chính thức, Cộng tác viên sẽ đưa tập hợp thay đổi của bạn vào kho lưu trữ chính thức.

Chúng tôi sử dụng các công cụ và quy trình sau:

  • Chúng tôi dùng Git làm hệ thống quản lý phiên bản của mình.
  • Chúng tôi sử dụng Maven cho hệ thống xây dựng cũng như hệ thống phân phối nhị phân.
  • Chúng tôi sử dụng codereview.appspot.com để xem xét mã. (Nhưng lưu ý rằng trong công cụ codereview.appspot.com, thuật ngữ "issue" có nghĩa là yêu cầu đánh giá mã, trong khi ở Công cụ theo dõi lỗi GitHub, "issue" là một yêu cầu tính năng hoặc báo cáo lỗi.)

Nếu bạn là nhà phát triển Eclipse, hãy sử dụng định dạng mã dành riêng cho dự án được chỉ định trong thư mục .settings do Eclipse tự động xử lý.

Thiết lập môi trường phát triển

Điều kiện tiên quyết

  1. Cài đặt Java 6. Bạn có thể cần đặt biến JAVA_HOME.
  2. Cài đặt Maven. (Tài liệu này giả định rằng bạn đã quen thuộc với các lệnh Maven.)
  3. Không bắt buộc: Cài đặt Android SDK và đặt biến ANDROID_HOME thành vị trí cài đặt cho Android.
  4. Cài đặt Git.

Thiết lập Git

Sử dụng lệnh git config để đặt tên hiển thị và địa chỉ email mặc định của bạn:

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS"

Xác thực bằng GitHub từ Git

Để có thể xem mã từ GitHub, bạn phải được xác thực bằng GitHub bằng cách sử dụng HTTP hoặc SSH. Trước khi tiếp tục với các hướng dẫn bên dưới, hãy đọc hướng dẫn của GitHub về cách bắt đầu sao chép bằng HTTPS hoặc SSH sao chép. Nếu muốn tìm hiểu thêm về Git nói chung, bạn nên sử dụng Pro Git.

Xem mã

Sử dụng HTTPS

Để xem kho lưu trữ thư viện trong chi nhánh phát triển "master", hãy chạy lệnh sau:

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

Sử dụng SSH

Để xem kho lưu trữ thư viện trong chi nhánh phát triển "master", hãy đảm bảo bạn có quyền ghi vào kho lưu trữ GitHub, sau đó chạy lệnh sau:

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

Để chuyển sang nhánh khác, ví dụ như 1.12:

git checkout --track origin/1.12

Để quay lại nhánh chính:

git checkout master

Để lấy những thay đổi mới nhất từ kho lưu trữ GitHub và cập nhật cây làm việc cục bộ của bạn lên cam kết mới nhất:

git pull

Maven

Cài đặt Dịch vụ Google Play

Lần đầu tiên thiết lập dự án, bạn cần cài đặt tệp google-play-services.jar. Cách thực hiện:

  1. Chạy Eclipse rồi chọn Window > Android SDK Manager (Trình quản lý SDK Android) và chạy android tại dòng lệnh.
  2. Di chuyển xuống cuối danh sách gói rồi chọn Extras > Google Play services (Dịch vụ bổ sung &gt).
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

Biên dịch dự án

mvn clean install

Maven cài đặt các tệp nhị phân được biên dịch vào một kho lưu trữ cục bộ (ví dụ: ~/.m2/repository). Nó tìm kiếm các tệp nhị phân trong kho lưu trữ đó trước khi tìm nạp từ kho lưu trữ trung tâm Maven.

Lưu ý: Thư viện này phụ thuộc vào google-http-java-client và google-oauth-java-client. Khi làm việc trên phiên bản mới của cả ba thư viện chưa được phát hành vào Trung tâm Maven, bạn phải biên dịch các thư viện đó theo thứ tự sau:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client Biên dịch theo thứ tự này đảm bảo rằng Maven chọn các tệp nhị phân được biên dịch để biên dịch thư viện phụ thuộc.

Quy trình xem xét mã

Tải tập lệnh upload.py xuống

Tải tập lệnh upload.py xuống và tùy ý thêm tập lệnh đó vào PATH.

Lần đầu tiên khi bạn chạy upload.py, ứng dụng sẽ yêu cầu bạn nhập mật khẩu dành riêng cho ứng dụng:

Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com
Password for your_email_address@yourdomain.com:

Đang chuẩn bị mã để xem xét

Trước khi gửi mã để xem xét, bạn phải chạy Clirr để phát hiện các vấn đề về khả năng tương thích ngược trong mã. Nếu xảy ra lỗi, bạn cần khắc phục lỗi hoặc cập nhật tệp clirr-ignored-DIFFs.xml.

mvn -q clirr:check

Bạn cũng phải chạy công cụ FindErrors để phát hiện lỗi trong mã. Nếu xảy ra lỗi, bạn cần khắc phục lỗi hoặc cập nhật tệp findbugs-excluded.xml. (Lưu ý rằng FindErrors rất chậm).

mvn findbugs:check

Sau khi thay đổi của bạn vượt qua mọi bài kiểm thử, hãy thêm thay đổi vào chỉ mục (vùng lưu trữ Git):

git add .

Kiểm tra kỹ xem toàn bộ tệp mà bạn đã thêm, sửa đổi hoặc xoá đã được phản ánh trong chỉ mục:

git status

Trong đầu ra git status, hãy kiểm tra phần có tên "Thay đổi cần cam kết."

Bắt đầu xem xét mã

Khi đã sẵn sàng để được xem xét, hãy tạo một vấn đề mới trên codereview.appspot.com: 

upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

Sau khi bạn thực hiện nhiều thay đổi hơn, hãy áp dụng các thay đổi mới. Để tải bản vá mới lên, ví dụ: để phát hành số 123456, hãy chạy lệnh sau: 

upload.py --rev=HEAD -i 123456

Để có thêm tuỳ chọn, hãy chạy upload.py --help.

Nếu muốn sử dụng quy trình công việc GitHub điển hình, thì có lẽ bạn đã tìm được kho lưu trữ GitHub và tạo một nhánh cho tính năng mới này hoặc bản sửa lỗi. Khi bạn gửi yêu cầu xem xét mã từ nhánh phát triển của riêng mình, hãy đảm bảo rằng nhánh của bạn sẽ được đồng bộ hoá với kho lưu trữ ngược dòng. Để biết thêm thông tin, hãy xem bài viết trợ giúp về GitHub về cách đồng bộ hoá nhánh phát triển (multik).

Bạn cũng có thể sử dụng upload.py cho các thay đổi được cam kết tại địa phương.

upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

Người đánh giá mã

Nếu bạn là người đánh giá mã, hãy nhập và kiểm thử các thay đổi trước khi phê duyệt, sau đó xác nhận và đẩy các thay đổi vào kho lưu trữ từ xa.

Nhập một tập hợp thay đổi

Để sớm phát hiện lỗi, hãy nhớ kéo những thay đổi mới nhất trên kho lưu trữ từ xa vào cây làm việc của bạn. Hãy đảm bảo cây làm việc của bạn sạch và chỉ mục của bạn trống.

Cách lấy và hợp nhất các thay đổi mới nhất từ kho lưu trữ từ xa:

git pull

Cách kiểm tra xem có nội dung gì trong cây và chỉ mục đang hoạt động:

git status

Cách nhập bản vá vào bản sao Git cục bộ:

  1. Mở vấn đề trong codereview.appspot.com.
  2. Để tìm bản vá được đề cập, hãy tìm "Tải xuống thô" ở trên cùng bên phải của thông số bản vá.
  3. Nhấp vào "raw" để lấy URL để nhập tệp.
  4. Lưu tệp diff thô vào máy cục bộ có tên như issue123456.diff.
  5. Chuyển đến cây làm việc Git cục bộ và áp dụng sự khác biệt bằng lệnh patch:
patch -p1 < issue123456.diff

Để kiểm tra kỹ xem bạn đã nhập đúng sự khác biệt hay chưa, hãy thực hiện git diff trong cây làm việc.

Kiểm thử setset thay đổi

Để chạy kiểm thử và cài đặt, hãy dùng lệnh sau:

mvn clean install checkstyle:check

Đang phê duyệt tập hợp thay đổi trên codereview.appspot.com

Nhìn chung, mã không được đẩy vào kho lưu trữ GitHub cho đến khi người đánh giá mã đáp ứng yêu cầu về mã đã sẵn sàng. Tại thời điểm đó, quy ước là trả lời bằng thông báo "LGTM" (Có vẻ ổn với tôi).

Xác nhận mã

Quan trọng: Trước khi xác nhận mã, hãy kéo những thay đổi mới nhất vào cây làm việc và cập nhật cây làm việc của bạn lên bản cam kết mới nhất trong kho lưu trữ GitHub:

git pull

Nếu có xung đột, hãy giải quyết xung đột, sau đó đảm bảo tất cả kiểm thử để vượt qua.

Cách cam kết mã cục bộ: 

git commit

Nhập một thông báo như sau (giả sử bạn đang khắc phục hoặc triển khai Vấn đề 123, như liệt kê trong Công cụ theo dõi lỗi của GitHub):

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

Trước dấu hai chấm đầu tiên và nội dung mô tả:

  • Nếu đây là cách khắc phục sự cố trên Công cụ theo dõi lỗi, hãy đưa vào số sự cố, như được minh họa.
  • Nếu đây là thay đổi cho một nhánh cụ thể, hãy thêm số nhánh.
  • Bạn sẽ là committer của cam kết này, nhưng vui lòng ghi nhận tác giả cho thay đổi bằng cách đánh dấu chúng là author (--author=<author>).

Sau đó, hãy luôn đính kèm đường liên kết dẫn đến vấn đề trên trang web đánh giá mã. Đường liên kết này rất quan trọng vì nếu không có đường liên kết này, sẽ không có cách nào thuận tiện để xác định bài đánh giá mã được liên kết với một bản cam kết. Điều này rất hữu ích trong việc duy trì nhật ký thảo luận.

Để đẩy thay đổi vào kho lưu trữ GitHub:

git push

Nếu trong git push, bạn nhận được thông báo lỗi về việc bản cập nhật bị từ chối (có thể bạn đã quên chạy git pull), thì đây là cách hợp nhất với các thay đổi mới nhất và đẩy các thay đổi của bạn vào kho lưu trữ từ xa: 

git pull
git commit
git push

Đang đóng vấn đề

Hãy nhớ đóng vấn đề trong công cụ xem xét mã. Cách thực hiện:

  1. Chọn vấn đề đó trong codereview.appspot.com.
  2. Nhấp vào "X" ở trên cùng bên trái, trước "Id&"

Gửi một tập hợp thay đổi

Nếu vì lý do nào đó bạn quyết định không gửi một tập hợp thay đổi mà bạn đã nhập, hãy sử dụng lệnh sau để xoá nội dung đó. Hãy thận trọng: Nó thực sự sẽ xoá tất cả các thay đổi cục bộ của bạn. 

git checkout -- .