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 cho cộng tác viên

Trước khi đóng góp bất kỳ thay đổi mã nào cho AOSP, bạn phải đọc Tiêu đề và thoả thuận cấp phép cho người đóng góp 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 rằng 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.

Lưu ý: Để thay đổi các dự án cấp trên mà Android sử dụng, bạn cần thực hiện trực tiếp các thay đổi đó đối với dự án đó. Để biết thêm thông tin, hãy xem phần Đóng góp cho các dự án cấp trên.

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 có 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 so với 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ộ trong môi trường làm việc của bạn và không có trong Gerrit hoặc 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 tạo. Ví dụ:

   project frameworks/native/                      branch mynewbranch
   

   Lưu ý: Bạn cũng có thể sử dụng repo branches để lấy danh sách tất cả các nhánh, trong đó nhánh hiện tại (nếu có) sẽ có dấu hoa thị (*) ở phía trước.

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
   

   Lưu ý: Để chỉ đồng bộ hoá dự án hiện tại, hãy thêm dấu chấm (.) vào lệnh repo sync: repo sync .. Việc đồng bộ hoá dự án hiện tại sẽ nhanh hơn so với việc đồng bộ hoá toàn bộ kho lưu trữ.

   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 phần 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ính năng 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ờ chạy 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 làm 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 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 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. Metalava xác thực các nội dung bổ sung và sửa đổi đối với API nền tảng.

4. Tạo Android.

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

Đặt và xác nhận thay đổi

Ghi thay đổi là đơn vị cơ bản của tính năng kiểm soát bản sửa đổi trong Git và bao gồm một bản tổng quan nhanh về 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 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.

   Lưu ý: Nếu bạn chỉ muốn theo dõi các thay đổi đối với một tệp cụ thể, hãy sử dụng git add filename.
   Lưu ý: Ngoài việc theo dõi các thay đổi đối với tệp, bạn có thể sử dụng git add để thực hiện các thao tác khác, chẳng hạn như sửa đổi và xoá tệp.

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 tiền tố để mô tả phần bạn đã thay đổi, theo sau là nội dung mô tả về thay đổi bạn đã thực hiện trong thay đổi này, chẳng hạn như ví dụ sau đây chứa nội dung 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 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ẽ hữu ích cho những người khác cần tham khảo lại nội dung thay đổi. Hãy 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 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 thay đổi bạn đã thực hiện trong tất cả dự á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.

   Lưu ý: Để chỉ tải các thay đổi lên trong dự án hiện tại, hãy thêm dấu chấm (.) vào lệnh repo upload: repo upload ..
   Lưu ý: Nếu bạn đang thực hiện một thay đổi cần thay đổi các tệp trong nhiều dự án, hãy sử dụng một chủ đề trong Gerrit để liên kết các thay đổi với nhau, bất kể bạn sử dụng repo upload hay repo upload .. Chủ đề Gerrit đảm bảo rằng các thay đổi được giữ lại với nhau cho mục đích kiểm thử trước khi gửi và thông qua tính năng hợp nhất tự động. Để biết thêm thông tin, hãy xem bài viết Sử dụng chủ đề

   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)?
   

   Lưu ý: Nếu đã bắt đầu nhiều nhánh trong cùng một kho lưu trữ, bạn sẽ được nhắc chọn những nhánh cần tải lên bằng cách bỏ ghi chú các nhánh đó trong trình chỉnh sửa văn bả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 một đường liên kết đến các thay đổi 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 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 chủ sở hữu mã có thể xem xét nội dung thay đổi của bạn.

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

   Lưu ý: Để hiểu cách xác định chủ sở hữu, hãy tham khảo phần phụ trợ tìm chủ sở hữu.

   Nút SEND (GỬI) đượ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 xem xét thay đổi.

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 thay đổi, hãy kiểm tra các biểu tượng sau bên cạnh các tệp trong thay đổi:

• (biểu tượng dấu kiểm): Đã được chủ sở hữu mã phê duyệt
• (biểu tượng dấu thập): Chủ sở hữu mã chưa 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 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 nội dung cập nhật, bạn có thể sửa đổi thay đổi của mình trong Git. Thao tác này sẽ tạo ra một nhóm bản vá mới cho cùng một thay đổi.

Lưu ý: Nếu đã tạo các nhánh khác và thực hiện các thay đổi khác sau khi tải một thay đổi lên, thì có thể bạn đang làm việc trong nhánh của một trong các thay đổi đó chứ không phải nhánh của thay đổi ban đầu. Vì vậy, trước khi có thể giải quyết ý kiến phản hồi cho nhánh ban đầu, bạn phải chuyển đến nhánh đó bằng lệnh repo start EXISTING_BRANCH_NAME.

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 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ác thay đổi khác được gửi đến cây nguồn xung đột với thay đổi của bạn, bạn sẽ nhận được thông báo về 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 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 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.