Trang này được dịch bởi Cloud Translation API.

Cách đóng góp

Thoả thuận cấp phép cho 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 Thỏa thuận cấp phép cộng tác viên (CLA) của cá nhân hoặc công ty:

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 cá nhân.
Nếu bạn làm việc cho một công ty, thì công ty của bạn phải gửi một thoả thuận cấp phép công ty (CLA) để cho biết rằng bạn được phép đóng góp tác phẩm của mình cho thư viện khách hàng này.

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 CLA. Sau khi nhận được email, chúng tôi có thể thêm bạn vào danh sách người đóng góp 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:

Ký Thoả thuận cấp phép cộng tác viên, như mô tả ở trên.
Tham gia nhóm thảo luận của chúng tôi.
Thiết lập môi trường phát triển của bạn.
Liên kết từng tập thay đổi 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 GitHub của chúng tôi. Tạo một Vấn đề mới (nếu chưa có) rồi giao cho chính bạn.
Hãy kiểm tra mã, tạo vấn đề mới trên codereview.appspot.com và hoàn tất quy trình xem xét mã. Hướng dẫn chi tiết cho tất cả các quy trình này được cung cấp dưới đây.
Sau khi mã của bạn được xem xét và bạn được phê duyệt, hãy cam kết mã. Nếu bạn không phải là 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 sử 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 xin 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ã, trong khi trong Công cụ theo dõi lỗi GitHub, "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 được 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

Cài đặt Java 6. Bạn có thể cần đặt biến JAVA_HOME.
Cài đặt Maven. (Tài liệu này giả định rằng bạn đã làm quen với các lệnh Maven cơ bản.)
Không bắt buộc: Cài đặt SDK Android rồi đặt biến ANDROID_HOME thành vị trí cài đặt cho Android.
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 bằng GitHub trong Git

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

Xem xét mã

Sử dụng HTTPS

Để xem kho lưu trữ thư viện trong 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 nhánh phát triển "chính", 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 một nhánh thay thế, ví dụ 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

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

Chạy Eclipse rồi chọn Window > Android SDK Manager (Cửa sổ > Trình quản lý SDK Android) hoặc chạy android ở dòng lệnh.
Di chuyển xuống cuối danh sách gói rồi chọn Extras > Dịch vụ 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

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). Google Play sẽ 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 một phiên bản mới của cả 3 thư viện chưa được phát hành lên trung tâm Maven, bạn phải biên dịch các thư viện đó theo thứ tự sau:

google-http-java-client
google-oauth-java-client
google-api-java-client Việc biên dịch theo thứ tự này đảm bảo rằng Maven chọn các tệp nhị phân đã 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 load.py xuống

Tải tập lệnh upload.py xuống và thêm tập lệnh này vào PATH của bạn (không bắt buộc).

Trong lần đầu tiê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ã đi 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ã của mình. Nếu có lỗi được báo cáo, bạn cần khắc phục 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 ra lỗi trong mã. Nếu có báo cáo lỗi, bạn cần khắc phục hoặc cập nhật tệp findbugs-exclusion.xml. (Lưu ý rằng FindBugs 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 (khu vực thử nghiệm Git):

git add .

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

git status

Trong đầu ra git status, hãy đánh dấu mục có tên là "Các thay đổi cần cam kết".

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

Khi đã sẵn sàng xem xét, hãy tạo 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 ...

Mẹo: Nếu bạn muốn người đánh giá nhìn thấy vấn đề và chỉ những người có tên trong dòng CC, hãy sử dụng tuỳ chọn --private.

Sau khi bạn thực hiện thêm thay đổi, hãy giai đoạn các thay đổi mới của bạn. Để tải bản vá mới lên, ví dụ như để phát hành bản vá 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 thích quy trình công việc GitHub thông thường, bạn có thể đã phát triển kho lưu trữ GitHub và tạo một nhánh cho tính năng mới hoặc bản sửa lỗi này. 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 phát triển của bạn được đồng bộ hoá với kho lưu trữ ngược dòng. Để biết thêm thông tin, hãy xem phần trợ giúp về GitHub về cách đồng bộ hoá một nhánh phát triển.

Bạn cũng có thể sử dụng upload.py cho các tập hợp thay đổi được cam kết cục bộ.

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 xem xét mã, hãy nhập và kiểm thử các tập hợp thay đổi trước khi phê duyệt, sau đó cam kết và đẩy tập hợp thay đổi vào kho lưu trữ từ xa.

Nhập 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 trong kho lưu trữ từ xa vào cây hoạt động của bạn. Hãy đảm bảo cây đang hoạt động sạch và chỉ mục 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 cây đang hoạt động và chỉ mục có những gì:

git status

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

Mở vấn đề trong codereview.appspot.com.
Đối với bản vá được đề cập, hãy tìm mục "Download thô" (Tải dữ liệu xuống) ở trên cùng bên phải của thông số kỹ thuật của bản vá.
Nhấp vào "thô" để lấy URL cho tệp cần nhập.
Lưu tệp so sánh thô vào máy cục bộ bằng tên nhưissue123456.diff.
Chuyển đến cây hoạt động Git cục bộ của bạn và áp dụng điểm khác biệt bằng lệnh patch:

patch -p1 < issue123456.diff

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

Kiểm thử tập hợp thay đổi

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

mvn clean install checkstyle:check

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

Nhìn chung, bạn không thể đẩy mã đến kho lưu trữ GitHub cho đến khi người xem xét mã hài lòng rằng mã đã sẵn sàng. Về điểm đó, quy ước là trả lời bằng thông điệp "LGTM" (Có vẻ ổn với tôi).

Xác nhận mã

Lưu ý 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 rồi cập nhật cây làm việc lên lệnh xác nhận mới nhất trong kho lưu trữ GitHub:

git pull

Nếu có bất kỳ xung đột nào, hãy giải quyết các xung đột đó, sau đó nhớ thực hiện lại tất cả các lượt kiểm thử.

Để 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 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à bản sửa lỗi cho một vấn đề trên Công cụ theo dõi lỗi, hãy bao gồm số sự cố như minh hoạ.
Nếu đây là thay đổi đối với một nhánh cụ thể, hãy bao gồm số nhánh.
Bạn sẽ là committer của thay đổi này, nhưng vui lòng ghi nhận tác giả của thay đổi bằng cách đánh dấu chúng là author (--author=<author>).

Sau nội dung mô tả, luôn bao gồm một đường liên kết đế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ó, sẽ không có cách nào thuận tiện để tìm hiểu bài đánh giá mã liên kết với một lượt cam kết. Điều này sẽ hữu ích cho việc duy trì nhật ký thảo luận.

Cách chuyển nội dung thay đổi sang 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 các bản cập nhật bị từ chối (có thể bạn đã quên chạy git pull), thì sau đây là cách hợp nhất với những 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

Đóng vấn đề

Hãy nhớ đóng vấn đề trong công cụ xem xét mã. Để thực hiện việc này:

Chọn vấn đề trong codereview.appspot.com.
Nhấp vào dấu "X" ở trên cùng bên trái, trước "Mã nhận dạng".

Huỷ vá một tập hợp thay đổi

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

git checkout -- .