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 .

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 dữ liệu đầu ra của git status, hãy kiểm tra phần "Các thay đổi cần cam kết".

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

Khi đã sẵn sàng để chúng tôi 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 thay đổi thêm, hãy triển khai các thay đổi mới đó. Để tải bản vá mới lên, ví dụ: với số phát hành 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 bạn thích GitHub quy trình công việc, có thể bạn đã chia nhánh 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 gửi mã xem xét các yêu cầu từ nhánh phát triển của riêng bạn, 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 của GitHub về cách đồng bộ hoá nhánh phát triển.

Bạn cũng có thể sử dụngupload.py cho các 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 ...

Nhân viên đánh giá mã

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

Nhập một nhóm thay đổi

Để sớm phát hiện lỗi, hãy nhớ lấy những thay đổi mới nhất trên điều khiển từ xa kho lưu trữ vào cây làm việc. Đảm bảo cây hoạt động sạch sẽ 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

Để kiểm tra nội dung trong cây và chỉ mục đang hoạt động, hãy làm như sau:

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. Đối với bản vá được đề cập, hãy tìm mục "Tải xuống dữ liệu thô" ở trên cùng bên phải của thông số của bản vá.
  3. Nhấp vào "thô" để lấy URL cho tệp cần nhập.
  4. Lưu tệp điểm khác biệt thô vào máy cục bộ bằng tên như sau vấn đề123456.diff.
  5. 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 cách sử dụng 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 git diff trong cây hoạt động của bạn.

Kiểm thử nhóm thay đổi

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

mvn clean install checkstyle:check

Phê duyệt mộ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 đánh giá mã hài lòng rằng mã đã sẵn sàng. Vào thời điểm đó, quy ước là trả lời với thông báo "LGTM" (Có vẻ tốt với tôi).

Xác nhận mã

Lưu ý quan trọng: Trước khi bạn 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 từ GitHub kho lưu trữ:

git pull

Nếu có bất kỳ xung đột nào, hãy giải quyết chúng, sau đó đảm bảo gửi tất cả các thử nghiệm để 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ư được liệt kê trên GitHub Công cụ theo dõi lỗi):

#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 thêm mã số vấn đề như được minh hoạ.
  • Nếu đây là thay đổi cho một nhánh cụ thể, hãy bao gồ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 tác giả của thay đổi bằng cách đánh dấu chúng là author (--author=<author>).

Theo phần mô tả, luôn cung cấp đường liên kết đến vấn đề trong quá trình xem xét mã của bạn. Đườ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, thì không có cách nào thuận tiện để chỉ ra quy trình đánh giá mã liên kết với một cam kết, hữu ích cho lưu giữ lịch sử của cuộc thảo luận.

Cách đẩ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), 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 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:

  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 phần "Mã nhận dạng".

Huỷ vá một nhóm thay đổi

Nếu vì lý do nào đó bạn quyết định không thực hiện một nhóm thay đổi mà bạn đã nhập, hãy sử dụng sau đây để loại bỏ dữ liệu đó. Hãy thận trọng: Thao tác này sẽ xoá tất cả các thay đổi cục bộ của bạn theo đúng nghĩa đen. 

git checkout -- .