Gửi bản vá

Trang này mô tả toàn bộ quá trình gửi bản vá cho Dự án mã nguồn mở Android (AOSP), bao gồm cách yêu cầu xem xét và theo dõi các thay đổi của bạn bằng Gerrit . Gerrit là một hệ thống đánh giá mã dựa trên web dành cho các dự án sử dụng Git. Gerrit khuyến khích việc sử dụng Git tập trung hơn bằng cách cho phép tất cả người dùng được ủy quyền gửi các thay đổi, những thay đổi này sẽ tự động được hợp nhất nếu họ vượt qua quá trình xem xét mã. Ngoài ra, Gerrit giúp việc xem xét trở nên dễ dàng, hiển thị các thay đổi cạnh nhau trong trình duyệt và cho phép nhận xét nội tuyến.

Điều kiện tiên quyết

Để bắt đầu, hãy đảm bảo bạn đã thực hiện những điều sau:

Tài nguyên

  • Để biết chi tiết về Repo và Git, hãy xem trang Công cụ kiểm soát nguồn .
  • Để biết thông tin về các vai trò khác nhau trong cộng đồng Nguồn mở Android, hãy xem trang Vai trò dự án .
  • Để biết thông tin cấp phép về việc đóng góp mã cho nền tảng Android, hãy xem trang Giấy phép .

Định cấu hình Git

Để sử dụng Gerrit, email của bạn phải được liên kết với Tài khoản Google đã đăng ký. Chạy các lệnh sau để định cấu hình Git bằng tên và địa chỉ email được liên kết với Tài khoản Google đã đăng ký:

git config --global user.name Your Name
git config --global user.email your_email@gmail.com
    

Xác thực với máy chủ

Nếu bạn chia sẻ địa chỉ IP với những người dùng khác, hạn ngạch có thể được kích hoạt ngay cả đối với các kiểu sử dụng thông thường. Ví dụ: điều này có thể xảy ra khi nhiều người dùng đồng bộ hóa ứng dụng khách mới từ cùng một địa chỉ IP trong một khoảng thời gian ngắn. Quyền truy cập được xác thực sử dụng hạn ngạch riêng cho từng người dùng, bất kể địa chỉ IP. Để đọc về cách kích hoạt quyền truy cập được xác thực, hãy xem Sử dụng xác thực .

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

Đối với mỗi thay đổi bạn định thực hiện, hãy bắt đầu một nhánh mới trong kho Git có liên quan:

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

git add -A
git commit -s

Thay đổi mô tả

  • Dòng 1: Tiêu đề

    Cung cấp bản tóm tắt một dòng ( tối đa 50 ký tự)

    Định dạng này được Git và Gerrit sử dụng cho nhiều màn hình khác nhau. Đây là phần quan trọng nhất, dày đặc nhất trong thông điệp cam kết của bạn. Hãy cân nhắc sử dụng tiền tố để mô tả khu vực bạn đã thay đổi, theo sau là mô tả về thay đổi bạn đã thực hiện trong cam kết này, chẳng hạn như thay đổi có ui làm tiền tố:

    ui: Removes deprecated widget

  • Dòng 2: Trống

    Luôn để trống dòng này.

  • Dòng 3: Thân

    Viết mô tả dài hơn, bắt đầu từ dòng này.

    Điều này phải bọc cứng ở mức tối đa 72 ký tự. Mô tả vấn đề mà thay đổi sẽ giải quyết và bằng cách nào. Mặc dù đây là tùy chọn khi triển khai các tính năng mới, nhưng nó sẽ rất hữu ích cho những người khác sau này nếu họ đề cập đến thay đổi này, đặc biệt là đối với việc gỡ lỗi.

    Bao gồm một ghi chú ngắn gọn về bất kỳ giả định hoặc thông tin cơ bản nào có thể quan trọng khi người đóng góp khác làm việc trên tính năng này.

ID 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 của bạn.

Dưới đây là một thông báo cam kết ví dụ:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit
  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original.

git add -A
git commit --amend

Khi bạn tải lên bản vá đã sửa đổi, nó 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 đồng bộ hóa

Nếu các bản vá khác được gửi tới cây nguồn xung đột với bản vá của bạn, hãy đặt lại bản vá của bạn lên trên HEAD mới của kho lưu trữ nguồn. Để làm như vậy, hãy chạy lệnh này:

repo sync

Lệnh đồng bộ repo sync tìm nạp các bản cập nhật từ máy chủ nguồn, sau đó cố gắng tự động khởi động lại HEAD của bạn lên HEAD từ xa mới.

Nếu rebase tự động không thành công, hãy thực hiện rebase thủ công.

repo rebase

Một công cụ khác để giải quyết xung đột rebase là git mergetool . Khi bạn đã hợp nhất thành công các tệp xung đột, hãy chạy lệnh này:

git rebase --continue

Sau khi quá trình rebase tự động hoặc thủ công hoàn tất, hãy chạy repo upload để gửi bản vá rebase của bạn.

Sau khi hồ sơ được phê duyệt

Sau khi quá trình gửi vượt qua quá trình xem xét và xác minh, Gerrit sẽ tự động hợp nhất thay đổi vào kho lưu trữ công cộng. Những người dùng khác có thể chạy repo sync để đưa bản cập nhật vào máy khách cục bộ tương ứng của họ.

Đối với dự án thượng nguồn

Android sử dụng một số dự án nguồn mở khác, chẳng hạn như nhân Linux và WebKit, như được mô tả trong Quản lý phần mềm Android . Đối với hầu hết các dự án nằm trong external/ , hãy thực hiện các thay đổi ngược dòng, sau đó thông báo cho nhà bảo trì Android về bản phát hành ngược dòng mới có chứa các thay đổi của bạn.

Bạn cũng có thể tải lên các bản vá khiến bản phát hành ngược dòng mới bị theo dõi. Lưu ý rằng đây có thể là những thay đổi khó thực hiện nếu dự án được sử dụng rộng rãi trong Android, giống như hầu hết các dự án lớn hơn được đề cập bên dưới, thường được nâng cấp sau mỗi lần phát hành.

Một trường hợp đặc biệt thú vị là Bionic. Phần lớn mã có từ BSD, vì vậy trừ khi thay đổi là mã mới đối với Bionic, vui lòng thực hiện sửa lỗi ngược dòng, sau đó lấy một tệp hoàn toàn mới từ BSD thích hợp.

Nhân Android

Thực hiện tất cả các thay đổi ngược dòng. Để biết hướng dẫn chung, hãy làm theo Nguyên tắc đóng góp hạt nhân Android và trang Phát triển mã hạt nhân cho GKI .

ICU

Thực hiện tất cả các thay đổi đối với dự án ICU tại thư mục external/icu ( icu4c/icu4j/ ) trên Trang chủ ICU-TC . Xem Gửi yêu cầu tính năng và lỗi ICU để biết thêm. Thêm nhãn “android” vào tất cả các yêu cầu ngược dòng của Jira.

CLDR

Hầu hết dữ liệu ngôn ngữ trong ICU đều đến từ dự án Unicode CLDR . Gửi tất cả các yêu cầu ngược dòng theo Đóng góp cho CLDR và ​​thêm nhãn “android”.

LLVM/Clang/Trình biên dịch-rt

Thực hiện tất cả các thay đổi đối với các dự án liên quan đến LLVM ( external/clang , external/compiler-rt , external/llvm ) trên trang Cơ sở hạ tầng trình biên dịch LLVM .

mksh

Thực hiện tất cả các thay đổi đối với dự án MirBSD Korn Shell tại external/mksh bằng cách gửi email đến miros-mksh trên miền mirbsd.org (không cần đăng ký để gửi tại đó) hoặc tại Launchpad .

OpenSSL

Thực hiện tất cả các thay đổi đối với dự án OpenSSL tại external/openssl trên trang OpenSSL .

V8

Gửi tất cả các thay đổi đối với dự án V8 tại external/v8 trên trang vấn đề V8 . Xem Đóng góp cho V8 để biết chi tiết.

WebKit

Thực hiện tất cả các thay đổi đối với dự án WebKit tại external/webkit trên trang WebKit . Bắt đầu quá trình bằng cách gửi lỗi WebKit . Khi xảy ra lỗi, chỉ sử dụng Android cho các trường Nền tảngHệ điều hành nếu lỗi chỉ dành riêng cho Android. Các lỗi có nhiều khả năng nhận được sự chú ý của người đánh giá hơn sau khi bản sửa lỗi được đề xuất được thêm vào và các thử nghiệm được đưa vào. Xem Đóng góp mã cho WebKit để biết chi tiết.

zlib

Thực hiện tất cả các thay đổi đối với dự án zlib tại external/zlib trên trang chủ zlib .

,

Trang này mô tả toàn bộ quá trình gửi bản vá cho Dự án mã nguồn mở Android (AOSP), bao gồm cách yêu cầu xem xét và theo dõi các thay đổi của bạn bằng Gerrit . Gerrit là một hệ thống đánh giá mã dựa trên web dành cho các dự án sử dụng Git. Gerrit khuyến khích việc sử dụng Git tập trung hơn bằng cách cho phép tất cả người dùng được ủy quyền gửi các thay đổi, những thay đổi này sẽ tự động được hợp nhất nếu họ vượt qua quá trình xem xét mã. Ngoài ra, Gerrit giúp việc xem xét trở nên dễ dàng, hiển thị các thay đổi cạnh nhau trong trình duyệt và cho phép nhận xét nội tuyến.

Điều kiện tiên quyết

Để bắt đầu, hãy đảm bảo bạn đã thực hiện những điều sau:

Tài nguyên

  • Để biết chi tiết về Repo và Git, hãy xem trang Công cụ kiểm soát nguồn .
  • Để biết thông tin về các vai trò khác nhau trong cộng đồng Nguồn mở Android, hãy xem trang Vai trò dự án .
  • Để biết thông tin cấp phép về việc đóng góp mã cho nền tảng Android, hãy xem trang Giấy phép .

Định cấu hình Git

Để sử dụng Gerrit, email của bạn phải được liên kết với Tài khoản Google đã đăng ký. Chạy các lệnh sau để định cấu hình Git bằng tên và địa chỉ email được liên kết với Tài khoản Google đã đăng ký:

git config --global user.name Your Name
git config --global user.email your_email@gmail.com
    

Xác thực với máy chủ

Nếu bạn chia sẻ địa chỉ IP với những người dùng khác, hạn ngạch có thể được kích hoạt ngay cả đối với các kiểu sử dụng thông thường. Ví dụ: điều này có thể xảy ra khi nhiều người dùng đồng bộ hóa ứng dụng khách mới từ cùng một địa chỉ IP trong một khoảng thời gian ngắn. Quyền truy cập được xác thực sử dụng hạn ngạch riêng cho từng người dùng, bất kể địa chỉ IP. Để đọc về cách kích hoạt quyền truy cập được xác thực, hãy xem Sử dụng xác thực .

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

Đối với mỗi thay đổi bạn định thực hiện, hãy bắt đầu một nhánh mới trong kho Git có liên quan:

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

git add -A
git commit -s

Thay đổi mô tả

  • Dòng 1: Tiêu đề

    Cung cấp bản tóm tắt một dòng ( tối đa 50 ký tự)

    Định dạng này được Git và Gerrit sử dụng cho nhiều màn hình khác nhau. Đây là phần quan trọng nhất, dày đặc nhất trong thông điệp cam kết của bạn. Hãy cân nhắc sử dụng tiền tố để mô tả khu vực bạn đã thay đổi, theo sau là mô tả về thay đổi bạn đã thực hiện trong cam kết này, chẳng hạn như thay đổi có ui làm tiền tố:

    ui: Removes deprecated widget

  • Dòng 2: Trống

    Luôn để trống dòng này.

  • Dòng 3: Thân

    Viết mô tả dài hơn, bắt đầu từ dòng này.

    Điều này phải bọc cứng ở mức tối đa 72 ký tự. Mô tả vấn đề mà thay đổi sẽ giải quyết và bằng cách nào. Mặc dù đây là tùy chọn khi triển khai các tính năng mới, nhưng nó sẽ rất hữu ích cho những người khác sau này nếu họ đề cập đến thay đổi này, đặc biệt là đối với việc gỡ lỗi.

    Bao gồm một ghi chú ngắn gọn về bất kỳ giả định hoặc thông tin cơ bản nào có thể quan trọng khi người đóng góp khác làm việc trên tính năng này.

ID 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 của bạn.

Dưới đây là một thông báo cam kết ví dụ:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit
  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original.

git add -A
git commit --amend

Khi bạn tải lên bản vá đã sửa đổi, nó 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 đồng bộ hóa

Nếu các bản vá khác được gửi tới cây nguồn xung đột với bản vá của bạn, hãy đặt lại bản vá của bạn lên trên HEAD mới của kho lưu trữ nguồn. Để làm như vậy, hãy chạy lệnh này:

repo sync

Lệnh đồng bộ repo sync tìm nạp các bản cập nhật từ máy chủ nguồn, sau đó cố gắng tự động khởi động lại HEAD của bạn lên HEAD từ xa mới.

Nếu rebase tự động không thành công, hãy thực hiện rebase thủ công.

repo rebase

Một công cụ khác để giải quyết xung đột rebase là git mergetool . Khi bạn đã hợp nhất thành công các tệp xung đột, hãy chạy lệnh này:

git rebase --continue

Sau khi quá trình rebase tự động hoặc thủ công hoàn tất, hãy chạy repo upload để gửi bản vá rebase của bạn.

Sau khi hồ sơ được phê duyệt

Sau khi quá trình gửi vượt qua quá trình xem xét và xác minh, Gerrit sẽ tự động hợp nhất thay đổi vào kho lưu trữ công cộng. Những người dùng khác có thể chạy repo sync để đưa bản cập nhật vào máy khách cục bộ tương ứng của họ.

Đối với dự án thượng nguồn

Android sử dụng một số dự án nguồn mở khác, chẳng hạn như nhân Linux và WebKit, như được mô tả trong Quản lý phần mềm Android . Đối với hầu hết các dự án nằm trong external/ , hãy thực hiện các thay đổi ngược dòng, sau đó thông báo cho nhà bảo trì Android về bản phát hành ngược dòng mới có chứa các thay đổi của bạn.

Bạn cũng có thể tải lên các bản vá khiến bản phát hành ngược dòng mới bị theo dõi. Lưu ý rằng đây có thể là những thay đổi khó thực hiện nếu dự án được sử dụng rộng rãi trong Android, giống như hầu hết các dự án lớn hơn được đề cập bên dưới, thường được nâng cấp sau mỗi lần phát hành.

Một trường hợp đặc biệt thú vị là Bionic. Phần lớn mã có từ BSD, vì vậy trừ khi thay đổi là mã mới đối với Bionic, vui lòng thực hiện sửa lỗi ngược dòng, sau đó lấy một tệp hoàn toàn mới từ BSD thích hợp.

Nhân Android

Thực hiện tất cả các thay đổi ngược dòng. Để biết hướng dẫn chung, hãy làm theo Nguyên tắc đóng góp hạt nhân Android và trang Phát triển mã hạt nhân cho GKI .

ICU

Thực hiện tất cả các thay đổi đối với dự án ICU tại thư mục external/icu ( icu4c/icu4j/ ) trên Trang chủ ICU-TC . Xem Gửi yêu cầu tính năng và lỗi ICU để biết thêm. Thêm nhãn “android” vào tất cả các yêu cầu ngược dòng của Jira.

CLDR

Hầu hết dữ liệu ngôn ngữ trong ICU đều đến từ dự án Unicode CLDR . Gửi tất cả các yêu cầu ngược dòng theo Đóng góp cho CLDR và ​​thêm nhãn “android”.

LLVM/Clang/Trình biên dịch-rt

Thực hiện tất cả các thay đổi đối với các dự án liên quan đến LLVM ( external/clang , external/compiler-rt , external/llvm ) trên trang Cơ sở hạ tầng trình biên dịch LLVM .

mksh

Thực hiện tất cả các thay đổi đối với dự án MirBSD Korn Shell tại external/mksh bằng cách gửi email đến miros-mksh trên miền mirbsd.org (không cần đăng ký để gửi tại đó) hoặc tại Launchpad .

OpenSSL

Thực hiện tất cả các thay đổi đối với dự án OpenSSL tại external/openssl trên trang OpenSSL .

V8

Gửi tất cả các thay đổi đối với dự án V8 tại external/v8 trên trang vấn đề V8 . Xem Đóng góp cho V8 để biết chi tiết.

WebKit

Thực hiện tất cả các thay đổi đối với dự án WebKit tại external/webkit trên trang WebKit . Bắt đầu quá trình bằng cách gửi lỗi WebKit . Trong lỗi, chỉ sử dụng Android cho các trường Nền tảngHệ điều hành nếu lỗi chỉ dành riêng cho Android. Các lỗi có nhiều khả năng nhận được sự chú ý của người đánh giá hơn sau khi bản sửa lỗi được đề xuất được thêm vào và các thử nghiệm được đưa vào. Xem Đóng góp mã cho WebKit để biết chi tiết.

zlib

Thực hiện tất cả các thay đổi đối với dự án zlib tại external/zlib trên trang chủ zlib .