Gửi nội dung thay đổi mã

Trang này mô tả toàn bộ quy trình gửi thay đổi mã cho Dự án nguồn mở Android (AOSP), bao gồm cả cách yêu cầu xem xét và theo dõi các thay đổi của bạn.

AOSP dựa vào Gerrit, một hệ thống xem xét mã dựa trên web cho các dự án sử dụng Git.

Ký thoả thuận cấp phép của cộng tác viên

Trước khi đóng góp bất kỳ nội dung thay đổi mã nào cho AOSP, bạn phải đọc Thoả thuận cấp phép và tiêu đề của cộng tác viên rồi ký một trong các thoả thuận sau:

• Nếu bạn là một cộng tác viên cá nhân chỉ đóng góp thay mặt cho bạn, hãy ký Thoả thuận cấp phép cho cộng tác viên cá nhân.
• Nếu bạn là nhân viên làm việc cho một công ty, hãy đảm bảo công ty của bạn đã ký Thoả thuận cấp phép cho người đóng góp là công ty uỷ quyền cho bạn thay mặt công ty đóng góp.

Bắt đầu một nhánh

Đối với mỗi thay đổi mã mà bạn dự định thực hiện, hãy thực hiện các bước sau:

1. Bắt đầu một nhánh mới trong kho lưu trữ Git liên quan. Nhánh không phải là bản sao của các tệp gốc; đó là con trỏ đến một thay đổi cụ thể, giúp tạo các nhánh cục bộ và chuyển đổi giữa các nhánh đó một cách dễ dàng. Bằng cách sử dụng các nhánh, bạn có thể xác định các thay đổi từ các nhánh khác nhau. Chạy lệnh sau để bắt đầu một nhánh:

   repo start BRANCH_NAME

   Bạn có thể bắt đầu nhiều nhánh độc lập cùng một lúc trong cùng một kho lưu trữ. Nhánh BRANCH_NAME là cục bộ của không gian làm việc của bạn và không được đưa vào Gerrit hay trong cây nguồn cuối cùng. Nhánh cũng dành riêng cho dự án mà bạn đang làm việc. Vì vậy, nếu cần thay đổi các tệp trong nhiều dự án trong cùng một thay đổi, bạn sẽ cần một nhánh trong mỗi dự án mà bạn thay đổi tệp.

2. (không bắt buộc) Xác minh rằng nhánh đã được tạo:

   repo status .

   Bạn sẽ thấy nhánh mới được tạo. Ví dụ:

   project frameworks/native/                      branch mynewbranch

Thực hiện và thử nghiệm thay đổi của bạn

Hãy làm theo các bước sau để thực hiện và kiểm thử thay đổi:

1. Để đảm bảo bạn đang làm việc với cơ sở mã mới nhất, hãy đồng bộ hoá toàn bộ cơ sở mã:

   repo sync

   Nếu bạn gặp xung đột trong quá trình đồng bộ hoá, hãy tham khảo các bước 2-4 trong phần Giải quyết xung đột đồng bộ hoá.

2. Tìm mã cần thay đổi. Để tìm mã, hãy cân nhắc sử dụng tính năng Tìm kiếm mã Android. Bạn có thể sử dụng tính năng Tìm kiếm mã Android để xem mã nguồn AOSP như được trình bày khi bạn thực sự sử dụng mã nguồn đó. Để biết thêm thông tin, hãy xem Bắt đầu sử dụng tính năng Tìm kiếm mã. Để xem tất cả mã trong nhánh main trong tìm kiếm mã Android, hãy chuyển đến https://cs.android.com/android/platform/superproject/main.

3. Sửa đổi hoặc thêm tệp nguồn. Đối với mọi thay đổi đã thực hiện:

   • Xác định xem bạn có cần sử dụng cờ khởi chạy tính năng hay không và nếu có, hãy triển khai chúng cho mã mới của bạn.

   • Làm theo các phương pháp hay nhất trong phần Thêm tiêu đề giấy phép.

   • Đối với mã Java, hãy tuân theo kiểu mã Java của AOSP dành cho người đóng góp.

   • Một số phần của AOSP được viết bằng Kotlin (.kt) và bạn có thể sử dụng Kotlin trong các khu vực của nền tảng đã được viết bằng Kotlin. Để biết thêm thông tin về Kotlin trong Android, hãy xem Hướng dẫn về quy tắc lập trình Kotlin và Hướng dẫn về khả năng tương tác Kotlin-Java dành cho nhà phát triển Android. Để biết thêm hướng dẫn về Kotlin, hãy xem trang web về ngôn ngữ Kotlin.

   • Khi viết API, hãy tuân thủ Nguyên tắc về API Android. Hãy làm theo các nguyên tắc này để xem bối cảnh đằng sau các quyết định về API của Android. Các thao tác thêm và sửa đổi API nền tảng được Metalava xác thực.

4. Tạo Android.

5. Kiểm thử bản dựng.

Thử nghiệm và cam kết thay đổi của bạn

cam kết (commit) là đơn vị kiểm soát bản sửa đổi cơ bản trong Git và bao gồm thông tin tổng quan nhanh về cấu trúc thư mục cũng như nội dung tệp của toàn bộ dự án. Thực hiện theo các bước sau để cam kết thay đổi của bạn:

1. Theo mặc định, Git sẽ đăng ký nhưng không theo dõi các thay đổi mà bạn thực hiện. Để hướng dẫn Git theo dõi các thay đổi của bạn, bạn phải đánh dấu hoặc phân đoạn các thay đổi đó để đưa vào một thay đổi. Chạy lệnh sau để đưa thay đổi vào giai đoạn:

   git add -A

   Lệnh này theo dõi những thay đổi mà bạn đã thực hiện đối với bất kỳ tệp nào.

2. Lấy các tệp trong vùng lưu trữ tạm thời và xác nhận hoặc lưu trữ các tệp đó trong cơ sở dữ liệu cục bộ:

   git commit -s

   Theo mặc định, trình chỉnh sửa văn bản sẽ mở ra và bạn sẽ được nhắc cung cấp thông báo xác nhận.

3. Cung cấp thông báo cam kết theo định dạng sau:

   • Dòng 1: Dòng tiêu đề. Cung cấp bản tóm tắt một dòng về thay đổi (tối đa 50 ký tự). Hãy cân nhắc sử dụng các tiền tố để mô tả khu vực bạn đã thay đổi, theo sau là nội dung mô tả về thay đổi bạn đã thực hiện trong cam kết này, chẳng hạn như ví dụ sau đây về việc thay đổi giao diện người dùng:

     ui: Removes deprecated widget
     

   • Dòng 2: Dòng trống. Đặt một dòng trống sau dòng tiêu đề.

   • Dòng 3: Nội dung. Cung cấp một nội dung mô tả dài cố định ở tối đa 72 ký tự. Mô tả vấn đề mà sự thay đổi đó giải quyết và cách thức. Mặc dù phần nội dung là không bắt buộc, nhưng nó sẽ hữu ích cho những người cần xem lại thay đổi. Hãy nhớ ghi chú ngắn gọn về mọi giả định hoặc thông tin cơ bản có thể quan trọng khi một cộng tác viên khác sử dụng tính năng này.

   Để đọc bài đăng trên blog về nội dung mô tả tốt cho thay đổi (có ví dụ), hãy xem bài viết Cách viết thông báo thay đổi trên Git.

4. Lưu thay đổi.

Mã thay đổi duy nhất, tên và email của bạn (được cung cấp trong repo init) sẽ tự động được thêm vào thông báo cam kết.

Tải nội dung thay đổi lên để được xem xét

Sau khi bạn xác nhận thay đổi đối với nhật ký Git cá nhân, hãy tải thay đổi đó lên Gerrit:

1. Chạy lệnh sau để tải tất cả các cam kết trong tất cả dự án của bạn lên:

   repo upload

   Tất cả thay đổi trong tất cả dự án đều được đưa vào quá trình tải lên.

   Bạn sẽ được nhắc chạy tập lệnh hook.

2. Nhấn phím a rồi nhấn phím Enter.

   Bạn sẽ được nhắc phê duyệt nội dung tải lên:

   Upload project frameworks/native/ to remote branch main:
   branch BRANCH_NAME ( 1 commit, Wed Aug 7 09:32:33 2019 -0700):
          ff46b36d android codelab change
   to https://android-review.googlesource.com/ (y/N)?
   

3. Nhấn phím y rồi nhấn phím Enter để phê duyệt quá trình tải lên.

Bạn sẽ nhận được một thông báo tương tự như remote: SUCCESS.

Yêu cầu xem xét

Sau khi tải lên thành công, Repo sẽ cung cấp cho bạn đường liên kết đến các thay đổi của bạn trong Gerrit. Nhấp vào đường liên kết để xem các thay đổi của bạn trên máy chủ xem xét, thêm nhận xét hoặc yêu cầu người xem xét cụ thể cho nội dung thay đổi của bạn. Tất cả thay đổi đối với mã phải được chủ sở hữu mã thích hợp xem xét. Cách yêu cầu xem xét:

1. Trong Gerrit, hãy nhấp vào ĐỀ XUẤT CHỦ SỞ HỮU:

   

   Hình 1. Đề xuất đường liên kết đến chủ sở hữu trong Gerrit.

   Hộp thoại người đánh giá sẽ xuất hiện. Hộp thoại này chứa danh sách chủ sở hữu mã có thể xem xét thay đổi của bạn.

2. Nhấp vào chủ sở hữu mã để thêm họ vào bài đánh giá của bạn.

   Nút SEND (GỬI) được kích hoạt.

3. (Không bắt buộc) Nhập địa chỉ email của bất kỳ người nào khác mà bạn muốn xem lại thay đổi của mình.

4. (Không bắt buộc) Nhấp vào +1 bên cạnh mục Tự động gửi để tự động gửi nội dung thay đổi sau khi bạn nhận được phê duyệt. Nếu bạn không nhấp vào nút này, nhân viên của Google sẽ phải gửi thay đổi thay cho bạn.

5. Nhấp vào GỬI để gửi nội dung thay đổi đi xem xét.

Chủ sở hữu mã xem xét các thay đổi mã của bạn và đưa ra ý kiến phản hồi để bạn giải quyết hoặc phê duyệt các thay đổi đó.

Xác định trạng thái thay đổi

Để xác định trạng thái của các tệp trong nội dung thay đổi, hãy kiểm tra các biểu tượng sau bên cạnh các tệp trong nội dung thay đổi:

• done (biểu tượng dấu kiểm): Đã được chủ sở hữu mã phê duyệt
• clear (biểu tượng dấu thập): Không được chủ sở hữu mã phê duyệt
• access_time (biểu tượng đồng hồ): Đang chờ chủ sở hữu mã phê duyệt

Hình sau đây cho thấy các biểu tượng trạng thái này được áp dụng cho các tệp trong một thay đổi:

Hình 2. Ví dụ về các tệp có biểu tượng cho biết chủ sở hữu mã đã phê duyệt.

Giải quyết ý kiến phản hồi và tải nội dung thay thế lên

Nếu người đánh giá yêu cầu sửa đổi bản cập nhật của bạn, thì bạn có thể sửa đổi cam kết của mình trong Git, dẫn đến một bản vá mới cho cùng một thay đổi.

Cách giải quyết ý kiến phản hồi và sửa đổi nội dung thay đổi:

1. Làm theo các bước 2-4 trong phần Tạo và kiểm thử nội dung thay đổi.

2. Chạy các lệnh sau để sửa đổi nội dung thay đổi:

   git add -A
   git commit --amend

3. Tải nội dung thay đổi lên.

Khi bạn tải nội dung thay đổi đã sửa đổi lên, nội dung này sẽ thay thế nội dung gốc trên cả Gerrit và trong nhật ký Git cục bộ của bạn.

Giải quyết xung đột đồng bộ hoá

Nếu có những thay đổi khác được gửi tới cây nguồn xung đột với cây của bạn, thì bạn sẽ nhận được một thông báo cho biết đang có xung đột. Cách giải quyết xung đột:

1. Đảm bảo bạn đang dùng đoạn mã mới nhất:

   repo sync .

   Lệnh repo sync tìm nạp nội dung cập nhật từ máy chủ nguồn, sau đó cố gắng tự động đặt lại cơ sở HEAD của bạn vào HEAD từ xa mới.

2. Nếu không thành công khi tự động căn cứ lại, hãy căn cứ lại theo cách thủ công:

   repo rebase .

3. Giải quyết xung đột hợp nhất. Nếu không có phương thức ưu tiên để giải quyết các xung đột hợp nhất, bạn có thể sử dụng git mergetool để khắc phục xung đột giữa các tệp theo cách thủ công.

4. Khi bạn đã khắc phục thành công các tệp xung đột, hãy chạy lệnh này để áp dụng các thay đổi mới:

   git rebase --continue

Gửi nội dung thay đổi

Sau khi một nội dung gửi đi đã trải qua quy trình xem xét và xác minh, người đánh giá của Google phải gửi mã cho bạn. Người dùng khác có thể chạy repo sync để lấy bản cập nhật vào ứng dụng cục bộ tương ứng.

Sau khi nội dung bạn gửi được hợp nhất, bạn có thể truy cập vào trang tổng quan Tích hợp liên tục Android để theo dõi thời điểm nội dung bạn gửi được tích hợp vào cây.