Cách đóng góp

Thoả 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 bản vá mã của bạn, bạn cần gửi thông tin cá nhân hoặc Thoả thuận cấp phép cộng tác viên (CLA) cho công ty:

Truy cập vào 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 về cách ký và trả lại chứng từ. Sau khi nhận được, 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ề việc 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 theo 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.
  4. Liên kết từng thay đổi của bạn với một Sự cố (báo cáo lỗi hoặc tính năng) yêu cầu) trong Công cụ theo dõi lỗi của GitHub. Tạo Vấn đề mới nếu chưa có vấn đề rồi giao cho chính bạn.
  5. Hãy kiểm tra mã, báo cáo 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 cho tất cả những quy trình này.
  6. Sau khi mã của bạn được xem xét và bạn được phê duyệt, hãy cam kết sử dụng mã đó. Nếu bạn không phải là Cộng tác viên chính thức, một Cộng tác viên sẽ lấy bộ 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 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 để viết mã bài đánh giá. (Nhưng hãy lưu ý rằng trong công cụ codereview.appspot.com, thuật ngữ "vấn đề" có nghĩa là yêu cầu xem xét mã, còn ở Công cụ theo dõi lỗi GitHub, là một "vấn đề" là yêu cầu về 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 xử lý tự động.

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 phải đặt JAVA_HOME biến.
  2. Cài đặt Maven. (Tài liệu này giả sử bạn đã biết cơ bản về các lệnh Maven.)
  3. Không bắt buộc: Cài đặt SDK Android và đặt biến ANDROID_HOME của bạn thành vị trí cài đặt cho Android.
  4. Cài đặt Git.

Thiết lập Git

Dùng lệnh git config để đặt tên hiển thị và địa chỉ email mặc định:

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

Xác thực với GitHub qua Git

Để có thể xem mã lấy trên GitHub, bạn phải được xác thực bằng GitHub bằng HTTP hoặc SSH. Trước khi tiếp tục với bên dưới, hãy đọc GitHub hướng dẫn về cách tải bắt đầu bằng việc sao chép HTTPS hoặc SSH. Nếu bạn muốn tìm hiểu thêm về Git trong nói chung, Pro Git là một nguồn tài nguyên hữu ích.

Đang kiểm tra mã

Sử dụng HTTPS

Để xem kho lưu trữ thư viện trong "chính" phát triển chi nhánh, 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 "chính" phát triển nhánh, tạo chắc chắn rồi có quyền ghi vào kho lưu trữ GitHub, rồi chạy lệnh sau:

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

Cách chuyển sang một nhánh thay thế, ví dụ: 1.12:

git checkout --track origin/1.12

Cách chuyển về 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 mã cục bộ cây làm việc cho 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 google-play-services.jar. Để thực hiện việc này:

  1. Khởi chạy Eclipse và chọn Window > Android SDK Manager hoặc chạy android ở dòng lệnh.
  2. Di chuyển xuống cuối danh sách gói rồi chọn Thông tin bổ sung > Google Play luôn miễn phí.
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 đã 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 qua 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ả 3 thư viện chưa phát hành vào Maven Central, bạn phải biên dịch chúng theo thứ tự sau:

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

Quy trình xem xét mã

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

Tải tập lệnh upload.py xuống và tuỳ ý thêm đường dẫn đó vào PATH của bạn.

Trong lần đầu tiên chạy upload.py, ứng dụng sẽ yêu cầu bạn cung cấ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ã đi xem xét, bạn phải chạy Clirr để quay ngược lại các vấn đề về khả năng tương thích trong mã của bạn. Nếu được báo cáo lỗi, bạn cần hãy sửa lỗi hoặc cập nhật tệp clirr-ignored-differences.xml.

mvn -q clirr:check

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

mvn findbugs:check

Sau khi thay đổi của bạn vượt qua tất cả các kiểm thử, hãy thêm thay đổi đó vào chỉ mục (ví dụ về bước chạy thử nghiệm Git diện tích):

git add