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 ...
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 -- .