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:
- Đã khởi tạo môi trường xây dựng của bạn
- Đã tải nguồn
- Tạo mật khẩu bằng cách sử dụng trình tạo mật khẩu.
- Ký thỏa thuận cấp phép cộng tác viên
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.
-
Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.
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
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/
và 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ảng và Hệ đ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:
- Đã khởi tạo môi trường xây dựng của bạn
- Đã tải nguồn
- Tạo mật khẩu bằng cách sử dụng trình tạo mật khẩu.
- Ký thỏa thuận cấp phép cộng tác viên
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.
-
Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.
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
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/
và 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ảng và Hệ đ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 .