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.

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:

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:

  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à 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.

  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à thử nghiệm thay đổi của bạn:

  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 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á.

  2. 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 đế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:

  4. Xây dựng Android.

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

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:

  1. 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.

  2. 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.

  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 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.

  4. 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:

  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

    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.

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

  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 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:

  1. Trong Gerrit, hãy nhấp vào CHỦ SỞ HỮU SUGGEST:

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

    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 đã đượ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 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.

  5. 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:

Ví dụ về các tệp có biểu tượng cho thấy sự phê duyệt của chủ sở hữu mã

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:

  1. 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.

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

    git add -A
git commit --amend

  3. Tải thay đổi của bạn lên.

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:

  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 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ên HEAD từ xa mới.

  2. 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 .

  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 để khắc phục xung đột giữa các tệp theo cách thủ công.

  4. 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.