Gửi thay đổi mã

Trang này mô tả toàn bộ quy trình gửi một thay đổi về 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 đánh giá mã dựa trên web cho các dự án sử dụng Git.

Ký thoả thuận cấp phép cho người đóng góp

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

• Nếu là một cộng tác viên cá nhân chỉ đóng góp thay mặt cho chính mình, hãy ký Thoả thuận cấp phép cho cộng tác viên cá nhân.
• Là nhân viên làm việc cho một tập đoàn, hãy đảm bảo rằng công ty của bạn đã ký Thoả thuận cấp phép dành cho cộng tác viên là doanh nghiệp cho phép bạn đóng góp thay mặt cho công ty.

Tạo một nhánh

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

1. Bắt đầu một nhánh mới trong kho lưu trữ Git có 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ỏ đến một cam kết cụ thể, giúp việc tạo các nhánh cục bộ và chuyển đổi giữa các nhánh trở thành một thao tác đơn giản. Bằng cách sử dụng các nhánh, bạn có thể xác định những thay đổi của từng nhánh. Chạy lệnh này để bắt đầu một nhánh:

   repo start BRANCH_NAME

   Bạn có thể bắt đầu một số 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à nhánh cục bộ trong không gian làm việc của bạn và không có trên Gerrit hoặc trong cây nguồn cuối cùng. Các nhánh cũng dành riêng cho dự án mà bạn đang tham gia. Vì vậy, nếu cần thay đổi tệp trong các dự án khác nhau 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 tạo. Ví dụ:

   project frameworks/native/                      branch mynewbranch

Thực hiện và kiểm thử thay đổi

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 đến 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 Android Code Search. Bạn có thể sử dụng Công cụ tìm kiếm mã Android để xem mã nguồn AOSP khi mã nguồn này được bố trí trong quá trình bạn thực sự sử dụng. Để biết thêm thông tin, hãy xem bài viết Làm quen với tính năng Tìm kiếm mã. Để xem tất cả mã trong nhánh phát hành AOSP mới nhất trong Android Code Search, hãy chuyển đến https://cs.android.com/android/platform/superproject/.

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ờ ra mắt tính năng hay không. Nếu có, hãy triển khai các cờ này cho mã mới.

   • 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 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 thích Kotlin-Java của nhà phát triển Android. Để biết hướng dẫn đầy đủ hơ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 tham khảo các nguyên tắc này để biết bối cảnh đằng sau các quyết định về API của Android. Các điểm bổ sung và sửa đổi đối với API nền tảng được xác thực bằng Metalava.

4. Xây dựng Android.

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

Giai đoạn và xác nhận thay đổi

Cam kết là đơn vị cơ bản của chế độ kiểm soát phiên bản trong Git và bao gồm một ảnh chụp nhanh cấu trúc thư mục và nội dung tệp cho toàn bộ dự án. Hãy làm theo các bước sau để xác nhận thay đổi:

1. Theo mặc định, Git sẽ đăng ký nhưng không theo dõi những 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 dàn xếp những thay đổi đó để đưa vào một cam kết. Chạy lệnh này để dàn xếp thay đổi:

   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 khu vực dàn dựng và xác nhận hoặc lưu trữ chúng trong cơ sở dữ liệu cục bộ:

   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 được nhắc cung cấp một thông báo cam kết.

3. Cung cấp thông báo xác nhận 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 tiền tố để mô tả khu vực bạn đã thay đổi, sau đó là nội dung mô tả về thay đổi mà bạn đã thực hiện trong cam kết này, chẳng hạn như ví dụ sau đây có chứa một thay đổi về giao diện người dùng:

     ui: Removes deprecated widget
     

   • Dòng 2: Dòng trống. Theo sau tiêu đề là một dòng trống.

   • Dòng 3: Nội dung. Cung cấp nội dung mô tả dài có tối đa 72 ký tự. Mô tả vấn đề mà thay đổi này giải quyết và cách giải quyết. Mặc dù phần nội dung là không bắt buộc, nhưng phần này sẽ giúp ích cho những người khác cần tham khảo lại nội dung thay đổi. Nhớ thêm một ghi chú ngắ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 làm việc trên tính năng này.

   Để đọc một blog về nội dung mô tả cam kết hiệu quả (kèm ví dụ), hãy xem bài viết Cách viết thông báo cam kết Git.

4. Lưu cam kết.

Mã thay đổi duy nhất, tên và email của bạn (được cung cấp trong quá trình 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 để xem xét

Sau khi bạn xác nhận thay đổi vào 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 của bạn lên trong tất cả các dự án:

   repo upload

   Tất cả các thay đổi trong mọi 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.

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

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

   Upload project frameworks/native/ to remote branch android16-release:
   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 việc 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 một đườ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 thay đổi của bạn. 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:

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

   

   Hình 1. Đề xuất liên kết 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 những người sở hữu mã có thể xem xét thay đổi của bạn.

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

   Nút GỬI sẽ được kích hoạt.

3. (Không bắt buộc) Nhập địa chỉ email của những người khác mà bạn muốn họ xem xét thay đổi của bạn.

4. Nhấp vào GỬI để gửi yêu cầu thay đổi đi xem xét.

Chủ sở hữu mã sẽ xem xét các thay đổi về mã của bạn và nếu chấp nhận, họ sẽ chọn lọc thay đổi đó và hợp nhất vào nhánh phát triển nội bộ.

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 đánh dấu): Được chủ sở hữu mã phê duyệt
• clear (biểu tượng dấu gạch chéo): Chủ sở hữu mã không 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 sự phê duyệt của chủ sở hữu mã.

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

Nếu người đánh giá yêu cầu bạn sửa đổi nội dung cập nhật, bạn có thể sửa đổi cam kết của mình trong Git. Thao tác này sẽ tạo ra một bộ 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 thay đổi:

1. Làm theo các bước 2 đến 4 trong phần Thực hiện và kiểm thử thay đổi.

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

   git add -A
   git commit --amend

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

Khi bạn tải thay đổi đã sửa đổi lên, thay đổi đó sẽ thay thế thay đổi ban đầu trên cả Gerrit và trong nhật ký Git cục bộ.

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

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

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

   repo sync .

   Lệnh repo sync sẽ 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 lên HEAD từ xa mới.

2. Nếu không thể tự động điều chỉnh cơ sở, hãy điều chỉnh cơ sở 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 xung đột hợp nhất, bạn có thể sử dụng git mergetool để tự khắc phục xung đột giữa các tệp.

4. Khi bạn đã sửa thành công các tệp xung đột, hãy chạy lệnh này để áp dụng các cam kết mới:

   git rebase --continue

Gửi thay đổi

Sau khi một bản gửi vượt qua quy trình xem xét và xác minh, chủ sở hữu mã sẽ gửi mã cho bạn, trên nhánh mà thay đổi được xem xét hoặc vào một nhánh nội bộ.

Sau khi yêu cầu của bạn đượ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 yêu cầu của bạn được tích hợp vào cây.