Hướng dẫn đóng góp

Dự án Go chào đón mọi người đóng góp.

Tài liệu này là hướng dẫn giúp bạn đi qua quy trình đóng góp cho dự án Go, vốn hơi khác một chút so với quy trình của các dự án mã nguồn mở khác. Chúng tôi giả định bạn đã hiểu cơ bản về Git và Go.

Ngoài những thông tin ở đây, cộng đồng Go còn duy trì một trang wiki CodeReview. Bạn cứ thoải mái đóng góp cho wiki khi tìm hiểu về quy trình xét duyệt.

Lưu ý rằng front end gccgo nằm ở nơi khác; xem Đóng góp cho gccgo.

Trở thành người đóng góp

Tổng quan

Bước đầu tiên là đăng ký làm người đóng góp cho Go và cấu hình môi trường của bạn. Dưới đây là danh sách các bước bắt buộc cần làm theo:

• Bước 0: Chọn một tài khoản Google duy nhất mà bạn sẽ dùng để đóng góp cho Go. Dùng tài khoản đó cho tất cả các bước sau và bảo đảm rằng git được cấu hình để tạo commit với địa chỉ e-mail của tài khoản đó.
• Bước 1: Ký và gửi một CLA (Contributor License Agreement).
• Bước 2: Cấu hình thông tin xác thực cho Git repository của Go. Truy cập go.googlesource.com, bấm “Generate Password” trên thanh menu góc trên bên phải của trang, rồi làm theo hướng dẫn.
• Bước 3: Đăng ký Gerrit, công cụ code review mà nhóm Go sử dụng, bằng cách truy cập trang này. CLA và việc đăng ký chỉ cần làm một lần cho tài khoản của bạn.
• Bước 4: Cài đặt git-codereview bằng cách chạy go install golang.org/x/review/git-codereview@latest

Nếu muốn, có một công cụ tự động dẫn bạn qua các bước này. Chỉ cần chạy:

$ go install golang.org/x/tools/cmd/go-contrib-init@latest
$ cd /code/to/edit
$ go-contrib-init

Phần còn lại của chương này nói chi tiết hơn về các hướng dẫn trên. Nếu bạn đã hoàn tất các bước ở trên (thủ công hoặc qua công cụ), hãy nhảy tới Trước khi đóng góp mã nguồn.

Bước 0: Chọn một tài khoản Google

Một đóng góp cho Go được thực hiện thông qua một tài khoản Google với một địa chỉ e-mail cụ thể. Hãy bảo đảm dùng cùng một tài khoản trong suốt quy trình và cho mọi đóng góp về sau của bạn. Bạn có thể phải quyết định dùng địa chỉ cá nhân hay địa chỉ công ty. Lựa chọn này phụ thuộc vào việc ai sẽ sở hữu bản quyền đối với mã nguồn mà bạn viết và gửi đi. Bạn có thể muốn bàn bạc chủ đề này với người sử dụng lao động của mình trước khi quyết định dùng tài khoản nào.

Tài khoản Google có thể là tài khoản e-mail Gmail, tài khoản tổ chức G Suite, hoặc tài khoản gắn với một địa chỉ e-mail bên ngoài. Chẳng hạn, nếu bạn cần dùng một e-mail công ty sẵn có mà không được quản lý qua G Suite, bạn có thể tạo một tài khoản gắn với địa chỉ e-mail sẵn có của bạn.

Bạn cũng cần bảo đảm rằng công cụ Git của bạn được cấu hình để tạo commit bằng địa chỉ e-mail bạn đã chọn. Bạn có thể cấu hình Git ở phạm vi toàn cục (mặc định cho mọi dự án), hoặc cục bộ (cho một dự án cụ thể). Bạn có thể kiểm tra cấu hình hiện tại bằng lệnh sau:

$ git config --global user.email  # check current global config
$ git config user.email           # check current local config

Để đổi địa chỉ đã cấu hình:

$ git config --global user.email [email protected]   # change global config
$ git config user.email [email protected]            # change local config

Bước 1: Contributor License Agreement

Trước khi gửi thay đổi đầu tiên của bạn cho dự án Go, bạn phải hoàn tất một trong hai CLA sau đây. Việc bạn nên ký CLA nào phụ thuộc vào ai sở hữu bản quyền công việc của bạn.

• Nếu bạn là người giữ bản quyền, bạn sẽ cần đồng ý với individual contributor license agreement, có thể hoàn tất trực tuyến.
• Nếu tổ chức của bạn là người giữ bản quyền, tổ chức đó sẽ cần đồng ý với corporate contributor license agreement.\

Bạn có thể xem các thoả thuận mình đã ký và ký thoả thuận mới tại website Google Developers Contributor License Agreements. Nếu người giữ bản quyền cho đóng góp của bạn đã hoàn tất thoả thuận này trong khuôn khổ một dự án mã nguồn mở khác của Google, thì không cần hoàn tất lại.

Nếu người giữ bản quyền đối với mã nguồn bạn gửi có thay đổi—ví dụ, nếu bạn bắt đầu đóng góp mã nguồn thay mặt cho một công ty mới—hãy gửi thư tới mailing list golang-dev. Việc này giúp chúng tôi nắm được tình hình để bảo đảm một thoả thuận phù hợp được hoàn tất.

Bước 2: Cấu hình xác thực git

Repository chính của Go nằm tại go.googlesource.com, một máy chủ Git do Google vận hành. Việc xác thực trên máy chủ web được thực hiện qua tài khoản Google của bạn, nhưng bạn cũng cần cấu hình git trên máy tính của mình để truy cập nó. Hãy làm theo các bước sau:

1. Truy cập go.googlesource.com và bấm vào “Generate Password” trên thanh menu góc trên bên phải của trang. Bạn sẽ được chuyển hướng tới accounts.google.com để đăng nhập.
2. Sau khi đăng nhập, bạn sẽ được đưa tới một trang có tiêu đề “Configure Git”. Trang này chứa một script cá nhân hoá mà khi chạy cục bộ sẽ cấu hình Git để giữ khoá xác thực riêng của bạn. Khoá này được ghép cặp với một khoá được sinh ra và lưu trên máy chủ, tương tự cách hoạt động của khoá SSH.
3. Sao chép và chạy script này cục bộ trong terminal của bạn để lưu token xác thực bí mật vào một tệp .gitcookies. Nếu bạn dùng máy Windows và chạy cmd, bạn nên làm theo hướng dẫn trong khung màu vàng để chạy lệnh; nếu không thì chạy script thông thường.

Bước 3: Tạo một tài khoản Gerrit

Gerrit là một công cụ mã nguồn mở được các maintainer của Go dùng để thảo luận và xét duyệt mã nguồn gửi lên.

Để đăng ký tài khoản, truy cập go-review.googlesource.com/login/ và đăng nhập một lần bằng đúng tài khoản Google bạn đã dùng ở trên.

Bước 4: Cài đặt lệnh git-codereview

Mọi thay đổi đối với Go đều phải được xét duyệt trước khi được chấp nhận, bất kể ai thực hiện thay đổi đó. Một lệnh git tuỳ biến tên là git-codereview giúp việc gửi thay đổi lên Gerrit đơn giản hơn.

Cài đặt lệnh git-codereview bằng cách chạy,

$ go install golang.org/x/review/git-codereview@latest

Hãy bảo đảm git-codereview được cài vào đường dẫn shell của bạn, để lệnh git có thể tìm thấy nó. Kiểm tra rằng

$ git codereview help

in ra văn bản trợ giúp, chứ không phải lỗi. Nếu nó in ra lỗi, hãy bảo đảm rằng $GOPATH/bin nằm trong $PATH của bạn.

Trên Windows, khi dùng git-bash bạn phải bảo đảm rằng git-codereview.exe nằm trong exec-path của git. Chạy git --exec-path để biết vị trí đúng rồi tạo một liên kết tượng trưng hoặc đơn giản là chép tệp thực thi từ $GOPATH/bin vào thư mục này.

Trước khi đóng góp mã nguồn

Dự án hoan nghênh các patch mã nguồn, nhưng để bảo đảm mọi thứ được phối hợp tốt, bạn nên thảo luận về bất kỳ thay đổi đáng kể nào trước khi bắt tay vào làm. Chúng tôi khuyến nghị bạn báo hiệu ý định đóng góp của mình trong issue tracker, bằng cách mở một issue mới hoặc nhận một issue sẵn có.

Đóng góp ở đâu

Dự án Go gồm repository chính go, chứa mã nguồn của ngôn ngữ Go, cùng với nhiều repository golang.org/x/… Những repository này chứa các công cụ và hạ tầng đa dạng hỗ trợ Go. Ví dụ, golang.org/x/pkgsite là dành cho pkg.go.dev, golang.org/x/playground là dành cho Go playground, và golang.org/x/tools chứa nhiều công cụ Go khác nhau, bao gồm cả language server của Go, gopls. Bạn có thể xem danh sách tất cả các repository golang.org/x/… trên go.googlesource.com.

Kiểm tra issue tracker

Dù bạn đã biết mình muốn đóng góp gì, hay đang tìm một ý tưởng, issue tracker luôn là nơi đầu tiên cần tới. Các issue được triage để phân loại và quản lý luồng công việc.

Phần lớn các repo golang.org/x/… cũng dùng issue tracker chính của Go. Tuy nhiên, một vài repository trong số đó quản lý issue riêng, nên hãy chắc chắn kiểm tra đúng tracker của repository mà bạn muốn đóng góp.

Hầu hết issue sẽ được gắn một trong các nhãn luồng công việc sau:

• NeedsInvestigation: Issue chưa được hiểu đầy đủ và cần phân tích để hiểu nguyên nhân gốc rễ.
• NeedsDecision: issue đã được hiểu tương đối rõ, nhưng nhóm Go chưa quyết định cách xử lý tốt nhất. Tốt hơn là chờ có quyết định rồi mới viết mã. Nếu bạn quan tâm tới việc làm một issue đang ở trạng thái này, cứ thoải mái “ping” các maintainer trong phần chú thích của issue nếu đã một thời gian trôi qua mà chưa có quyết định.
• NeedsFix: issue đã được hiểu đầy đủ và có thể viết mã để sửa nó.

Bạn có thể dùng chức năng tìm kiếm của GitHub để tìm issue cần giúp đỡ. Ví dụ:

• Issue cần được điều tra: is:issue is:open label:NeedsInvestigation
• Issue cần được sửa: is:issue is:open label:NeedsFix
• Issue cần được sửa và đã có đề xuất thay đổi: is:issue is:open label:NeedsFix ("golang.org/cl" OR "go.dev/cl")
• Issue cần được sửa và chưa có đề xuất thay đổi: is:issue is:open label:NeedsFix NOT "golang.org/cl" NOT "go.dev/cl"

Mở một issue cho mọi vấn đề mới

Trừ những thay đổi hết sức vặt vãnh, mọi đóng góp đều nên được gắn với một issue đã có. Bạn cứ thoải mái mở một issue và thảo luận về kế hoạch của mình. Quy trình này cho mọi người cơ hội kiểm chứng thiết kế, giúp tránh trùng lặp công sức, và bảo đảm ý tưởng phù hợp với mục tiêu của ngôn ngữ và các công cụ. Nó cũng kiểm tra xem thiết kế có vững chắc hay không trước khi mã được viết ra; công cụ code review không phải là nơi để thảo luận ở mức cao.

Khi lên kế hoạch công việc, xin lưu ý rằng dự án Go theo chu kỳ phát triển sáu tháng cho repository Go chính. Nửa sau của mỗi chu kỳ là ba tháng feature freeze, trong đó chỉ các bản sửa lỗi và cập nhật tài liệu được chấp nhận. Đóng góp mới vẫn có thể được gửi trong thời gian feature freeze, nhưng chúng sẽ không được merge cho tới khi hết freeze. Việc freeze áp dụng cho toàn bộ repository chính cũng như cho mã nguồn trong các repository golang.org/x/… cần thiết để build các tệp nhị phân đi kèm bản release. Xem danh sách các package được vendor vào thư viện chuẩn và lệnh go.

Những thay đổi đáng kể đối với ngôn ngữ, thư viện hay công cụ (bao gồm các thay đổi API trong repo chính và mọi repo golang.org/x, cũng như thay đổi dòng lệnh của lệnh go) phải đi qua quy trình đề xuất thay đổi trước khi có thể được chấp nhận.

Các issue nhạy cảm liên quan tới bảo mật (chỉ những issue như vậy!) nên được báo cáo tới [email protected].

Gửi một thay đổi qua Gerrit

Chúng tôi khuyến khích dùng Gerrit để gửi thay đổi đi xét duyệt. Dù có đôi chút khó khăn ban đầu với những người mới chỉ quen luồng làm việc của GitHub, đây là luồng làm việc chính mà những người đóng góp cho dự án Go sử dụng, và nó mượt mà cùng đầy đủ tính năng hơn.

Các mục sau đây giới thiệu sơ lược cách gửi một thay đổi qua Gerrit. Để biết chi tiết hơn về việc tương tác với Gerrit, xem tài liệu của Gerrit. Cụ thể, chúng tôi khuyên bạn đọc các trang Review UI Overview và Basic Gerrit Walkthrough — For GitHub Users.

Tổng quan

Đây là tổng quan toàn bộ quy trình:

• Bước 1: Clone mã nguồn từ go.googlesource.com và bảo đảm nó ổn định bằng cách biên dịch và test nó một lần.

  Nếu bạn đang thay đổi repository Go chính:

  $ git clone https://go.googlesource.com/go
  $ cd go/src
  $ ./all.bash                                # compile and test

  Nếu bạn đang thay đổi một trong các repository golang.org/x/… (golang.org/x/tools, trong ví dụ này):

  $ git clone https://go.googlesource.com/tools
  $ cd tools
  $ go test ./...                             # compile and test

• Bước 2: Chuẩn bị thay đổi trong một branch mới, tạo ra từ branch master. Để commit các thay đổi, dùng git codereview change; lệnh đó sẽ tạo hoặc bổ sung vào một commit duy nhất trong branch.

  $ git checkout -b mybranch
  $ [edit files...]
  $ git add [files...]
  $ git codereview change   # create commit in the branch
  $ [edit again...]
  $ git add [files...]
  $ git codereview change   # amend the existing commit with new changes
  $ [etc.]

• Bước 3: Test các thay đổi của bạn, bằng cách chạy test trong package bạn đã sửa hoặc chạy lại all.bash.

  Trong repository Go chính:

  $ ./all.bash    # recompile and test

  Trong một repository golang.org/x/…:

  $ go test ./... # recompile and test

• Bước 4: Gửi các thay đổi đi xét duyệt tới Gerrit bằng git codereview mail (lệnh này không dùng e-mail, bất chấp cái tên của nó).

  $ git codereview mail     # send changes to Gerrit

• Bước 5: Sau khi được xét duyệt, áp dụng các thay đổi vào cùng một commit duy nhất và gửi lại lên Gerrit:

  $ [edit files...]
  $ git add [files...]
  $ git codereview change   # update same commit
  $ git codereview mail     # send to Gerrit again

Phần còn lại của mục này mô tả các bước trên chi tiết hơn.

Bước 1: Clone mã nguồn

Ngoài một bản cài đặt Go gần đây, bạn cần có một bản sao cục bộ của mã nguồn được checkout từ đúng repository. Bạn có thể checkout repo mã nguồn Go vào hệ thống tệp cục bộ ở bất cứ đâu bạn muốn, miễn là nằm ngoài GOPATH của bạn (mặc định là thư mục go trong thư mục home của bạn). Clone từ go.googlesource.com (không phải GitHub):

Repository Go chính:

$ git clone https://go.googlesource.com/go
$ cd go

Repository golang.org/x/…

(golang.org/x/tools trong ví dụ này):

$ git clone https://go.googlesource.com/tools
$ cd tools

Bước 2: Chuẩn bị thay đổi trong một branch mới

Mỗi thay đổi cho Go phải được thực hiện trong một branch riêng, tạo ra từ branch master. Bạn có thể dùng các lệnh git thông thường để tạo branch và thêm thay đổi vào vùng staging:

$ git checkout -b mybranch
$ [edit files...]
$ git add [files...]

Để commit thay đổi, thay vì git commit, hãy dùng git codereview change.

$ git codereview change
(open $EDITOR)

Bạn có thể soạn phần mô tả commit trong trình soạn thảo ưa thích như bình thường. Lệnh git codereview change sẽ tự động thêm một dòng Change-Id duy nhất gần cuối. Dòng đó được Gerrit dùng để khớp các lần tải lên liên tiếp của cùng một thay đổi. Đừng sửa hay xoá nó. Một Change-Id trông như thế này:

Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990

Công cụ này cũng kiểm tra rằng bạn đã chạy go fmt trên mã nguồn, và rằng commit message tuân theo định dạng được đề xuất.

Nếu bạn cần sửa lại các tệp, bạn có thể stage các thay đổi mới và chạy lại git codereview change: mỗi lần chạy tiếp theo sẽ bổ sung vào commit đã có trong khi vẫn giữ nguyên Change-Id.

Hãy bảo đảm bạn luôn giữ đúng một commit duy nhất trong mỗi branch. Nếu bạn lỡ thêm nhiều commit hơn, bạn có thể dùng git rebase để gộp chúng lại thành một commit duy nhất.

Bước 3: Test các thay đổi của bạn

Bạn đã viết và test mã của mình, nhưng trước khi gửi mã đi xét duyệt, hãy chạy toàn bộ test cho cả cây mã nguồn để bảo đảm các thay đổi không làm hỏng package hay chương trình khác.

Trong repository Go chính

Với các package của thư viện chuẩn, mọi test trong package đều phải pass:

$ go test

Bộ test ngắn cho toàn bộ cây mã nguồn có thể chạy bằng all.bash (Để build trên Windows thì dùng all.bat):

$ cd go/src
$ ./all.bash

Sau khi chạy một lúc và in ra rất nhiều kết quả test, lệnh sẽ kết thúc bằng dòng,

ALL TESTS PASSED

Bạn có thể dùng make.bash thay cho all.bash để chỉ build compiler và thư viện chuẩn mà không chạy bộ test. Khi công cụ go đã được build, nó sẽ được cài đặt thành bin/go trong thư mục bạn đã clone repository Go, và bạn có thể chạy trực tiếp từ đó. Xem thêm mục về cách test nhanh các thay đổi của bạn.

Trong các repository golang.org/x/…

Chạy test cho toàn bộ repository (golang.org/x/tools, trong ví dụ này):

$ cd tools
$ go test ./...

Nếu bạn quan tâm tới trạng thái build, bạn có thể xem Build Dashboard. Các test thất bại cũng có thể bị TryBot phát hiện trong quá trình code review.

Một số repository, như golang.org/x/vscode-go, sẽ có hạ tầng test khác, nên hãy luôn kiểm tra tài liệu của repository bạn đang làm việc. Tệp README ở thư mục gốc của repository thường có thông tin này.

Bước 4: Gửi thay đổi đi xét duyệt

Khi thay đổi đã sẵn sàng và đã được test trên toàn bộ cây mã nguồn, hãy gửi nó đi xét duyệt. Việc này được thực hiện bằng lệnh con mail, lệnh này bất chấp cái tên của nó lại không trực tiếp gửi thư gì cả; nó chỉ gửi thay đổi tới Gerrit:

$ git codereview mail

Gerrit gán cho thay đổi của bạn một số và một URL, mà git codereview mail sẽ in ra, đại loại như:

remote: New Changes:
remote:   https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments

Nếu bạn nhận được lỗi thay vì kết quả trên, hãy xem mục Xử lý lỗi khi mail.

Nếu thay đổi của bạn liên quan tới một GitHub issue đang mở và bạn đã tuân theo định dạng commit message được đề xuất, issue sẽ được một bot cập nhật sau vài phút, liên kết thay đổi trên Gerrit của bạn tới issue đó trong phần chú thích.

Bước 5: Sửa lại thay đổi sau khi được xét duyệt

Các maintainer của Go sẽ xét duyệt mã của bạn trên Gerrit, và bạn sẽ nhận được thông báo qua e-mail. Bạn có thể xem phần xét duyệt trên Gerrit và bình luận ở đó. Bạn cũng có thể trả lời bằng e-mail nếu muốn.

Nếu bạn cần sửa lại thay đổi của mình sau khi được xét duyệt, hãy sửa các tệp trong đúng branch bạn đã tạo trước đó, thêm chúng vào vùng staging của Git, rồi bổ sung vào commit bằng git codereview change:

$ git codereview change     # amend current commit
(open $EDITOR)
$ git codereview mail       # send new changes to Gerrit

Nếu bạn không cần đổi phần mô tả commit, chỉ cần lưu lại và thoát khỏi trình soạn thảo. Nhớ đừng đụng vào dòng Change-Id đặc biệt.

Một lần nữa, hãy bảo đảm bạn luôn giữ đúng một commit duy nhất trong mỗi branch. Nếu bạn lỡ thêm nhiều commit hơn, bạn có thể dùng git rebase để gộp chúng lại thành một commit duy nhất.

Gửi một thay đổi qua GitHub

Mặc dù luồng làm việc Gerrit được khuyến nghị và được hỗ trợ tốt hơn, những người đóng góp vốn đã quen với luồng làm việc GitHub vẫn có thể dùng chính quy trình đó để đóng góp cho Go. Dù các maintainer của Go dùng Gerrit để code review, một công cụ tên là GerritBot đã được tạo ra để đồng bộ pull request trên GitHub sang Gerrit.

Hãy mở một pull request trên GitHub như bình thường. GerritBot sẽ tạo một change list tương ứng trên Gerrit (một “CL”) và đăng một liên kết tới nó trong pull request GitHub của bạn; các cập nhật cho pull request cũng sẽ được phản ánh trong CL trên Gerrit. Khi ai đó bình luận trên CL, bình luận của họ cũng sẽ được đăng trong pull request của bạn, nên bạn sẽ nhận được thông báo.

Một số điều cần lưu ý:

• Bạn sẽ cần một tài khoản Gerrit để phản hồi những người xét duyệt, kể cả để đánh dấu phản hồi là ‘Done’ nếu bạn đã hiện thực theo đúng đề xuất. Bạn nên làm quen với Gerrit, chẳng hạn bằng cách lướt qua các CL đang mở, đăng ký nhận cập nhật về những CL thú vị (qua biểu tượng ngôi sao), hoặc xét duyệt hay cho +1 vào CL của người khác.
• Để cập nhật pull request với mã mới, chỉ cần push lên branch; bạn có thể thêm commit, hoặc rebase rồi force-push (cả hai cách đều được chấp nhận).
• Nếu yêu cầu được chấp nhận, mọi commit sẽ được squash, và phần mô tả commit cuối cùng sẽ được ghép từ tiêu đề và phần mô tả của pull request. Phần mô tả của từng commit riêng lẻ sẽ bị bỏ đi. Xem Viết commit message tốt để có vài gợi ý.
• Xem GerritBot FAQ để biết thêm chi tiết.

Commit message tốt

Commit message trong Go tuân theo một tập quy ước cụ thể, mà chúng tôi bàn tới trong mục này.

Đây là một ví dụ về commit message tốt:

math: improve Sin, Cos and Tan precision for very large arguments

The existing implementation has poor numerical properties for
large arguments, so use the McGillicutty algorithm to improve
accuracy above 1e10.

The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm

Fixes #159

Dòng đầu tiên

Dòng đầu tiên của phần mô tả thay đổi theo quy ước là một bản tóm tắt ngắn gọn một dòng về thay đổi, có tiền tố là package chính bị ảnh hưởng.

Một quy tắc kinh nghiệm là nó nên được viết sao cho hoàn thành câu “This change modifies Go to _____.” Nghĩa là nó không bắt đầu bằng chữ in hoa, không phải một câu hoàn chỉnh, và thực sự tóm tắt kết quả của thay đổi.

Sau dòng đầu tiên là một dòng trống.

Nội dung chính

Phần còn lại của mô tả sẽ nói rõ hơn và nên cung cấp bối cảnh cho thay đổi cùng giải thích nó làm gì. Hãy viết thành câu hoàn chỉnh với dấu câu đúng, giống như khi viết chú thích trong Go. Đừng dùng HTML, Markdown, hay bất kỳ ngôn ngữ đánh dấu nào khác. Văn bản nên được ngắt dòng ở khoảng 72 cột. Xem Commit messages để biết thêm chi tiết.

Hãy thêm mọi thông tin liên quan, chẳng hạn dữ liệu benchmark nếu thay đổi ảnh hưởng tới hiệu năng. Công cụ benchstat theo quy ước được dùng để định dạng dữ liệu benchmark cho phần mô tả thay đổi.

Tham chiếu tới issue

Ký hiệu đặc biệt “Fixes #12345” gắn thay đổi với issue 12345 trong issue tracker của Go. Khi thay đổi này rốt cuộc được áp dụng, issue tracker sẽ tự động đánh dấu issue là đã sửa.

Nếu thay đổi chỉ là một bước giải quyết một phần của issue, hãy viết “Updates #12345” thay vào đó. Việc này sẽ để lại một chú thích trong issue liên kết ngược tới thay đổi trên Gerrit, nhưng sẽ không đóng issue khi thay đổi được áp dụng.

Nếu bạn gửi một thay đổi cho repository golang.org/x/…, bạn phải dùng cú pháp đầy đủ mà GitHub hỗ trợ để bảo đảm thay đổi được liên kết tới issue trong repository chính, chứ không phải repository x/. Hầu hết issue được theo dõi trong issue tracker của repository chính. Dạng đúng là “Fixes golang/go#159”.

Quy trình xét duyệt

Mục này giải thích chi tiết quy trình xét duyệt và cách tiếp cận việc xét duyệt sau khi một thay đổi đã được gửi đi.

Những lỗi thường gặp của người mới

Khi một thay đổi được gửi lên Gerrit, nó thường được triage trong vòng vài ngày. Một maintainer sẽ xem qua và đưa ra một vài nhận xét ban đầu mà với những người đóng góp lần đầu thường tập trung vào hình thức cơ bản và các lỗi thường gặp. Những lỗi đó gồm:

• Commit message không tuân theo định dạng được đề xuất.
• Thiếu một GitHub issue được liên kết. Đại đa số thay đổi đều cần một issue được liên kết mô tả lỗi hoặc tính năng mà thay đổi đó sửa hoặc hiện thực, và đã phải có sự đồng thuận trên tracker trước khi tiến hành. Việc xét duyệt trên Gerrit không bàn về giá trị của thay đổi, mà chỉ bàn về cách hiện thực nó.
  Chỉ những thay đổi vặt vãnh hoặc thuần hình thức mới được chấp nhận mà không cần issue đi kèm.
• Thay đổi được gửi trong giai đoạn freeze của chu kỳ phát triển, khi cây mã nguồn đóng với các thay đổi thông thường. Trong trường hợp này, một maintainer có thể xét duyệt mã kèm một dòng như R=go1.12, nghĩa là nó sẽ được xét duyệt sau, khi cây mã nguồn mở ra cho một cửa sổ phát triển mới. Bạn cũng có thể tự thêm R=go1.XX dưới dạng bình luận nếu bạn biết rằng đây không phải khoảng thời gian phù hợp cho thay đổi đó.

Trybot

Sau khi đọc qua thay đổi của bạn lần đầu, các maintainer sẽ kích hoạt trybot, một cụm máy chủ sẽ chạy toàn bộ bộ test trên nhiều kiến trúc khác nhau. Hầu hết trybot hoàn thành trong vài phút, khi đó một liên kết sẽ được đăng trên Gerrit để bạn xem kết quả.

Nếu lần chạy trybot thất bại, hãy theo liên kết đó và xem toàn bộ log của các nền tảng mà test đã thất bại. Hãy cố hiểu cái gì đã hỏng, cập nhật patch của bạn để sửa, rồi tải lên lại. Các maintainer sẽ kích hoạt một lần chạy trybot mới để xem vấn đề đã được sửa chưa.

Đôi khi, cây mã nguồn có thể hỏng trên một số nền tảng trong vài giờ; nếu thất bại mà trybot báo có vẻ không liên quan tới patch của bạn, hãy vào Build Dashboard và kiểm tra xem cùng thất bại đó có xuất hiện trong những commit gần đây khác trên cùng nền tảng không. Trong trường hợp này, bạn cứ thoải mái viết một bình luận trên Gerrit để nói rằng thất bại đó không liên quan tới thay đổi của bạn, giúp các maintainer hiểu tình hình. Bạn cũng có thể tìm trong các GitHub issue theo thông báo lỗi thất bại đó hoặc duyệt các issue watchflakes cập nhật gần đây. Nếu thay đổi của bạn dựa trên một commit cũ hoặc có vẻ như ai đó đã sửa vấn đề rồi, hãy thử rebase lên commit master mới nhất bằng git rebase.

Xét duyệt

Cộng đồng Go rất coi trọng việc xét duyệt kỹ lưỡng. Hãy nghĩ về mỗi bình luận xét duyệt như một ticket: bạn được kỳ vọng sẽ “đóng” nó bằng cách hành động dựa trên nó, hoặc bằng cách hiện thực theo đề xuất, hoặc bằng cách thuyết phục người xét duyệt theo hướng khác.

Sau khi cập nhật thay đổi, hãy đọc lại các bình luận xét duyệt và bảo đảm trả lời từng bình luận một. Bạn có thể bấm nút “Done” để trả lời cho biết bạn đã hiện thực theo đề xuất của người xét duyệt; nếu không, hãy bấm “Reply” và giải thích vì sao bạn không làm vậy, hoặc bạn đã làm gì thay thế.

Việc một thay đổi trải qua nhiều vòng xét duyệt là hoàn toàn bình thường, với một hoặc nhiều người xét duyệt đưa ra bình luận mới mỗi lần rồi chờ một bản cập nhật trước khi xét duyệt tiếp. Chu trình này xảy ra ngay cả với những người đóng góp giàu kinh nghiệm, nên đừng nản lòng vì nó.

Quy ước bỏ phiếu

Khi gần đi tới quyết định, người xét duyệt sẽ áp một “lá phiếu” Code-Review cho thay đổi của bạn. Có hai lá phiếu khả dĩ:

• +2 Thay đổi được chấp thuận để merge. Chỉ các maintainer của Go (còn được gọi là “approver”) mới có thể bỏ phiếu +2.
• +1 Thay đổi trông ổn, nhưng hoặc là người xét duyệt đang yêu cầu vài chỉnh sửa nhỏ trước khi chấp thuận, hoặc họ không phải maintainer nên không thể chấp thuận, nhưng muốn khuyến khích việc chấp thuận.

Để được submit, một thay đổi phải có Code-Review +2 từ một maintainer.

Maintainer cũng có thể áp lá phiếu Hold +1 cho thay đổi, để đánh dấu một thay đổi chưa nên được submit lúc này (ví dụ, vì việc xét duyệt đề xuất cho API mới trong thay đổi đó chưa hoàn tất).

Để được submit, một thay đổi không được có bất kỳ lá phiếu Hold +1 nào từ maintainer.

Cuối cùng, để được submit, một thay đổi phải có sự tham gia của hai nhân viên Google, hoặc với vai trò người tải thay đổi lên hoặc với vai trò người xét duyệt bỏ phiếu ít nhất Code-Review +1. Yêu cầu này là vì lý do tuân thủ và bảo mật supply chain.

Submit một thay đổi đã được chấp thuận

Khi một thay đổi đã sẵn sàng, một maintainer sẽ submit thay đổi đó, việc này thêm nó thành một commit vào repository Gerrit.

Hai bước (chấp thuận và submit) là tách biệt vì trong một số trường hợp maintainer có thể muốn chấp thuận nhưng chưa submit ngay (chẳng hạn, cây mã nguồn đang tạm thời bị freeze).

Việc submit một thay đổi sẽ đưa nó vào repository. Phần mô tả thay đổi sẽ bao gồm một liên kết tới phần code review, và phần code review đó sẽ được cập nhật một liên kết tới thay đổi trong repository. Vì phương pháp dùng để tích hợp thay đổi là “Cherry Pick” của Git, các hash commit trong repository sẽ bị thay đổi bởi thao tác submit.

Nếu thay đổi của bạn đã được chấp thuận vài ngày mà chưa được submit, bạn cứ thoải mái viết một bình luận trên Gerrit để yêu cầu submit.

Thêm thông tin

Ngoài những thông tin ở đây, cộng đồng Go còn duy trì một trang wiki CodeReview. Bạn cứ thoải mái đóng góp cho trang này khi tìm hiểu thêm về quy trình xét duyệt.

Các chủ đề khác

Mục này gom lại một số nhận xét khác nằm ngoài quy trình issue/sửa mã/code review/submit.

Gopls

Khi làm việc trên repository Go chính và dùng gopls với trình soạn thảo của bạn, lệnh go mà gopls gọi phải tương ứng với phiên bản mã nguồn bạn đang làm việc. Lệnh go có thể được build bằng make.bash và thư mục bin nên được thêm vào PATH của bạn. Xem Gopls: Advanced topics để biết thêm chi tiết.

Tài liệu đầy đủ về Gopls có tại https://go.dev/gopls.

Header bản quyền

Các tệp trong repository Go không liệt kê tên tác giả, vừa để tránh rườm rà vừa để khỏi phải giữ cho danh sách luôn cập nhật. Thay vào đó, tên bạn sẽ xuất hiện trong change log.

Các tệp mới mà bạn đóng góp nên dùng header bản quyền chuẩn:

// Copyright 2026 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

Các tệp trong repository được ghi bản quyền theo năm chúng được thêm vào. Đừng cập nhật năm bản quyền trên những tệp bạn sửa.

Xử lý lỗi khi mail

Cách phổ biến nhất khiến lệnh git codereview mail thất bại là do địa chỉ e-mail trong commit không khớp với địa chỉ bạn đã dùng trong quy trình đăng ký.
Nếu bạn thấy một thứ đại loại như…

remote: Processing changes: refs: 1, done
remote:
remote: ERROR:  In commit ab13517fa29487dcf8b0d48916c51639426c5ee9
remote: ERROR:  author email address XXXXXXXXXXXXXXXXXXX
remote: ERROR:  does not match your user account.

thì bạn cần cấu hình Git cho repository này để dùng địa chỉ e-mail mà bạn đã đăng ký. Để đổi địa chỉ e-mail nhằm bảo đảm điều này không lặp lại, hãy chạy:

$ git config user.email [email protected]

Rồi đổi commit để dùng địa chỉ e-mail thay thế này bằng lệnh sau:

$ git commit --amend --author="Author Name <[email protected]>"

Rồi thử lại bằng cách chạy:

$ git codereview mail

Test nhanh các thay đổi của bạn

Chạy all.bash cho từng thay đổi nhỏ trong cây mã nguồn khá nặng nề. Dù rất nên chạy nó trước khi gửi một thay đổi đi, trong chu trình phát triển bình thường bạn có thể muốn chỉ biên dịch và test package mà bạn đang phát triển.

• Nói chung, bạn có thể chạy make.bash thay cho all.bash để chỉ build lại toolchain của Go mà không chạy toàn bộ bộ test. Hoặc bạn có thể chạy run.bash để chỉ chạy toàn bộ bộ test mà không build lại toolchain. Bạn có thể coi all.bash như là make.bash rồi tới run.bash.

• Trong mục này, chúng tôi sẽ gọi thư mục mà bạn đã clone repository Go vào là $GOROOT. Công cụ go được build bởi $GOROOT/src/make.bash sẽ được cài đặt vào $GOROOT/bin/go và bạn có thể gọi nó để test mã của mình. Chẳng hạn, nếu bạn đã sửa compiler và muốn test xem nó ảnh hưởng thế nào tới bộ test của dự án riêng của bạn, chỉ cần chạy go test bằng nó:

  $ cd <MYPROJECTDIR>
  $ $GOROOT/bin/go test

• Nếu bạn đang thay đổi thư viện chuẩn, có lẽ bạn không cần build lại compiler: bạn chỉ cần chạy test cho package mà bạn đã sửa. Bạn có thể làm điều đó bằng phiên bản Go bạn vẫn thường dùng, hoặc bằng compiler Go được build từ bản clone của bạn (đôi khi việc này là bắt buộc vì mã của thư viện chuẩn mà bạn đang sửa có thể cần một phiên bản mới hơn bản ổn định bạn đã cài).

  $ cd $GOROOT/src/crypto/sha1
  $ [make changes...]
  $ $GOROOT/bin/go test .

• Nếu bạn đang sửa chính compiler, bạn chỉ cần biên dịch lại công cụ compile (đây là tệp nhị phân nội bộ được go build gọi để biên dịch từng package). Sau đó, bạn sẽ muốn test nó bằng cách biên dịch hoặc chạy thứ gì đó.

  $ cd $GOROOT/src
  $ [make changes...]
  $ $GOROOT/bin/go install cmd/compile
  $ $GOROOT/bin/go build [something...]   # test the new compiler
  $ $GOROOT/bin/go run [something...]     # test the new compiler
  $ $GOROOT/bin/go test [something...]    # test the new compiler

  Điều tương tự cũng áp dụng cho các công cụ nội bộ khác của toolchain Go, như asm, cover, link, v.v. Chỉ cần biên dịch lại và cài đặt công cụ bằng go install cmd/<TOOL> rồi dùng tệp nhị phân Go đã build để test nó.

• Ngoài các test chuẩn theo từng package, còn có một bộ test ở mức cao nhất trong $GOROOT/test chứa nhiều test hộp đen và test hồi quy. Bộ test này được chạy bởi all.bash nhưng bạn cũng có thể chạy nó thủ công:

  $ $GOROOT/bin/go test cmd/internal/testdir

Chỉ định người xét duyệt / CC cho người khác

Trừ khi được nói rõ là khác đi, chẳng hạn trong phần thảo luận dẫn tới việc gửi thay đổi, tốt hơn là đừng chỉ định người xét duyệt. Mọi thay đổi đều được tự động CC tới mailing list [email protected]. Nếu đây là thay đổi đầu tiên của bạn, có thể có một khoảng trễ do kiểm duyệt trước khi nó xuất hiện trên mailing list, nhằm ngăn spam.

Bạn có thể chỉ định người xét duyệt hoặc CC cho các bên quan tâm bằng tuỳ chọn -r hoặc -cc. Cả hai đều nhận một danh sách địa chỉ e-mail ngăn cách bởi dấu phẩy:

$ git codereview mail -r [email protected] -cc [email protected],[email protected]

Đồng bộ bản sao của bạn

Trong lúc bạn làm việc, người khác có thể đã submit thay đổi vào repository. Để cập nhật branch cục bộ của bạn, hãy chạy

$ git codereview sync

(Bên dưới, lệnh này chạy git pull -r.)

Xét duyệt mã của người khác

Là một phần của quy trình xét duyệt, người xét duyệt có thể đề xuất thay đổi trực tiếp (trong luồng làm việc GitHub thì việc này tương đương với người khác đính kèm commit vào một pull request). Gerrit cung cấp các lệnh giúp bạn nhập về những thay đổi do lập trình viên khác đề xuất để bạn có thể xét duyệt/test chúng cục bộ. Từ trang Gerrit của CL mà bạn muốn nhập về, mở menu “⋮”, bấm liên kết “Download patch”. Tuỳ theo luồng làm việc git ưa thích của bạn, hãy chọn lệnh phù hợp. Các tuỳ chọn sẽ trông đại loại như thế này:

$ git fetch https://go.googlesource.com/review refs/changes/21/13245/1 && git checkout FETCH_HEAD

Để quay lại, hãy chuyển về branch bạn đang làm việc.

Thiết lập alias cho git

Lệnh git-codereview có thể chạy trực tiếp từ shell bằng cách gõ, chẳng hạn,

$ git codereview sync

nhưng sẽ tiện hơn nếu thiết lập alias cho chính các lệnh con của git-codereview, để lệnh trên trở thành,

$ git sync

Các lệnh con của git-codereview đã được chọn sao cho khác biệt với lệnh của chính Git, nên định nghĩa các alias này là an toàn. Để cài chúng, hãy chép đoạn văn bản sau vào tệp cấu hình Git của bạn (thường là .gitconfig trong thư mục home):

[alias]
	change = codereview change
	gofmt = codereview gofmt
	mail = codereview mail
	pending = codereview pending
	submit = codereview submit
	sync = codereview sync

Gửi nhiều thay đổi phụ thuộc nhau

Người dùng nâng cao có thể muốn xếp chồng các commit liên quan trong một branch duy nhất. Gerrit cho phép các thay đổi phụ thuộc lẫn nhau, tạo thành một chuỗi phụ thuộc như vậy. Mỗi thay đổi sẽ cần được chấp thuận và submit riêng nhưng sự phụ thuộc sẽ hiển thị cho người xét duyệt thấy.

Để gửi đi một nhóm thay đổi phụ thuộc nhau, hãy giữ mỗi thay đổi là một commit khác nhau dưới cùng một branch, rồi chạy:

$ git codereview mail HEAD

Hãy nhớ chỉ định rõ HEAD, điều thường không cần thiết khi gửi một thay đổi đơn lẻ. Chi tiết hơn có thể xem trong tài liệu git-codereview.

Minor Release

Nếu bạn muốn thực hiện một thay đổi lên branch release để backport, xem Minor Releases.