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.
AOSP dựa vào Gerrit, một hệ thống đánh giá mã dựa trên nền tảng 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:
- Với tư cách là cá nhân đóng góp chỉ thay mặt bạn, hãy ký Thoả thuận cấp phép cộng tác viên cá nhâ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 cộng tác viên cho doanh nghiệp cho phép 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 định thực hiện, hãy thực hiện các bước sau:
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à một con trỏ tới một xác nhận 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 thao tác gọn nhẹ. Bằng cách sử dụng các nhánh, bạn có thể xác định các thay đổi khác nhau. Chạy lệnh này để 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 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 bạn đang tham gia. Vì vậy, nếu cần thay đổi 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 nơi bạn thay đổi tệp.
(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à thử nghiệm thay đổi của bạn:
Để đả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 bất kỳ xung đột nào trong quá trình đồng bộ hoá, hãy tham khảo các bước 2-4 của bài viết Giải quyết xung đột đồng bộ hoá.
Tìm mã cần thay đổi. Để tìm mã, hãy cân nhắc sử dụng công cụ Tìm kiếm mã Android. Bạn có thể sử dụng Android Code Search (Tìm kiếm mã Android) để xem mã nguồn AOSP khi mã được bố trí khi bạn thực sự sử dụng mã đó. Để biết thêm thông tin, hãy xem Bắt đầu với 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 đếnhttps://cs.android.com/android/platform/superproject/main
.Sửa đổi hoặc thêm tệp nguồn. Đối với mọi thay đổi:
- Làm theo các phương pháp hay nhất trong nội dung 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 quy tắc Kotlin dành cho nhà phát triển Android và hướng dẫn về khả năng tương tác Kotlin-Java. Để biết thêm hướng dẫn chuyên sâu 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 của 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.
Giai đoạn thực hiện 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:
Theo mặc định, Git đă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, bạn phải đánh dấu hoặc đưa các thay đổi đó vào giai đoạn để đưa vào cam kết. Chạy lệnh này để triển khai thay đổi:
git add -A
Lệnh này theo dõi các thay đổi mà bạn đã thực hiện đối với bất kỳ tệp nào.
Lấy các tệp trong vùng chạy thử và cam kết hoặc lưu trữ các tệp đó trong cơ sở dữ liệu cục bộ của bạn:
git commit -s
Theo mặc định, một 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 cam kết.
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 nội dung 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. Theo sau tiêu đề bằng một dòng trống.
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 blog về nội dung mô tả cam kết phù hợp (kèm theo ví dụ), hãy xem bài viết Cách viết thông báo cam kết Git.
Lưu cam kết.
Một mã thay đổi duy nhất cũng như 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 thực hiện thay đổi đối với lịch sử Git cá nhân, hãy tải lên Gerrit:
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
Mọi thay đổi trong tất cả dự án đều được đưa vào tệp tải lên.
Bạn được nhắc chạy tập lệnh hook.
Nhấn phím a rồi nhấn phím Enter.
Bạn được nhắc phê duyệt quá trình 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)?
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 lại
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. Hãy 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 đánh giá cụ thể về thay đổi đó. Tất cả cá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:
Trong Gerrit, hãy nhấp vào CHỦ SỞ HỮU SUGGEST:
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.
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 đã được kích hoạt.
(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.
(Không bắt buộc) Nhấp vào dấu +1 bên cạnh mục Tự động gửi để tự động gửi nội dung thay đổi sau khi bạ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 phải gửi nội dung thay đổi cho bạn.
Nhấp vào GỬI để gửi nội dung thay đổi cho chúng tôi xem xét.
Chủ sở hữu mã xem xét các thay đổi đối vớ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:
- (biểu tượng dấu kiểm): Đã được chủ sở hữu mã phê duyệt
- (biểu tượng chữ thập): Không được chủ sở hữu mã phê duyệt
- (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 có thay đổi:
Hình 2. Ví dụ về các tệp có biểu tượng thể hiện sự phê duyệt của chủ sở hữu mã.
Giải quyết phản hồi và tải thay đổi 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.
Để giải quyết ý kiến phản hồi và sửa đổi nội dung thay đổi, hãy làm như sau:
Làm theo các bước từ 2 đến 4 trong bài viết Thực hiện và thử nghiệm thay đổi.
Chạy các lệnh sau để sửa đổi thay đổi của bạn:
git add -A git commit --amend
Khi bạn tải nội dung thay đổi đã sửa đổi lên, thay đổi này sẽ thay thế bản gốc cả trên Gerrit và trong lịch sử Git cục bộ của bạn.
Giải quyết xung đột khi đồ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:
Đả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 các bản cập nhật từ máy chủ nguồn, sau đó tìm cách tự động đặt lại cơ sởHEAD
trênHEAD
từ xa mới.Nếu quá trình gửi lại cơ sở dữ liệu tự động không thành công, hãy tiến hành khôi phục cơ sở dữ liệu theo cách thủ công:
repo rebase .
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 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.Sau 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 nội dung gửi vượt qua quy trình xem xét và xác minh, nhân viên đánh giá của Google phải gửi mã cho bạn. Những người dùng khác có thể chạy repo sync
để kéo bản cập nhật vào các ứng dụng cục bộ tương ứng.
Sau khi hợp nhất nội dung bạn gửi, bạn có thể truy cập vào trang tổng quan Tích hợp liên tục của Android để theo dõi thời điểm nội dung bạn gửi được tích hợp vào cây.