Git shortlog và mailmap: Tổng hợp người đóng góp đúng cách

Khi chuẩn bị ghi chú phát hành, nhóm thường cần biết những ai đã đóng góp trong một khoảng lịch sử. Một người dùng nhiều email có thể xuất hiện thành nhiều dòng, còn tài khoản tích hợp có thể bị nhầm với tác giả thay đổi. Git shortlog kết hợp mailmap giúp tạo danh sách dễ kiểm tra hơn mà không cần viết lại commit cũ.

1. Chọn phạm vi trước khi đếm

Ví dụ dưới đây giả định repository đã có hai tag v1.0.0 và v1.1.0. Thay bằng mốc thật đã được nhóm xác nhận:

git shortlog -sn v1.0.0..v1.1.0
git shortlog v1.0.0..v1.1.0

Theo tài liệu shortlog, lệnh nhóm lịch sử theo tác giả; -s chỉ giữ số lượng, -n sắp theo số commit. Bản không có -s giúp đọc thêm tiêu đề thay đổi. Luôn truyền revision rõ ràng để script không vô tình chuyển sang đọc stdin.

Khoảng hai chấm lấy commit có thể đi tới từ mốc mới nhưng không từ mốc cũ, không phải khoảng ngày trên lịch. Hãy lưu cả mã commit của hai đầu mốc vào hồ sơ báo cáo. Đừng đổi phạm vi giữa chừng rồi so sánh hai kết quả như cùng một tập dữ liệu.

2. Phân biệt author và committer

git shortlog -sn --group=author v1.0.0..v1.1.0
git shortlog -sn --group=committer v1.0.0..v1.1.0

Hai lệnh trả lời hai câu hỏi khác nhau. Ví dụ, người tạo thay đổi và người đưa commit vào lịch sử có thể không giống nhau. Với dự án có bot hoặc người bảo trì tích hợp patch, cần ghi rõ đang báo cáo trường nào.

Nếu chỉ muốn khảo sát commit không phải merge, thêm --no-merges, nhưng lưu lựa chọn đó trong phương pháp báo cáo. Không tự mặc định merge là đóng góp vô giá trị: một merge có thể chứa xử lý xung đột quan trọng.

3. Khi một người xuất hiện nhiều lần

Trước khi gộp, xác nhận với người đóng góp hoặc nguồn thông tin của dự án. Tên giống nhau không đủ chứng minh hai danh tính thuộc một người. Email dùng chung hoặc tài khoản bot cũng cần được giữ riêng theo thực tế.

Tạo hoặc bổ sung file .mailmap ở gốc repository, giữ nguyên các dòng đã có. Ví dụ dùng địa chỉ minh họa:

Minh Nguyen <minh@example.com> <minh.old@example.com>
Minh Nguyen <minh@example.com> <minh.work@example.com>

Theo gitmailmap, dạng này ánh xạ tên và email hiển thị dựa trên email cũ. Đây là chuẩn hóa cách trình bày danh tính trong công cụ hỗ trợ mailmap, không thay đổi nội dung hoặc hash của commit lịch sử.

Đưa file qua review trước khi commit để cả nhóm dùng chung quy tắc. Không dùng mailmap để nhận công của người khác hoặc che nguồn gốc thực sự của thay đổi. File cũng không xóa email cũ khỏi đối tượng Git; yêu cầu bảo vệ dữ liệu cần được xử lý riêng.

4. Kiểm tra ánh xạ trước khi dùng báo cáo

git check-mailmap "Old Minh <minh.old@example.com>"
git shortlog -sne v1.0.0..v1.1.0

git check-mailmap cho phép kiểm tra một danh tính cụ thể. Với ví dụ trên, kết quả mong đợi là Minh Nguyen <minh@example.com>. Tùy chọn -e của shortlog hiển thị email để kiểm tra nội bộ; bỏ nó khi không cần đưa email vào báo cáo công khai.

So sánh trước và sau trên cùng phạm vi. Nếu chỉ thay cách gộp tác giả, tổng số commit được đếm không nên tự tăng hoặc giảm. Nếu một người biến mất hoặc tổng số đổi bất thường, kiểm tra lại đầu mốc, bộ lọc và quy tắc ánh xạ trước khi kết luận.

5. Đếm commit không phải đánh giá con người

Một commit có thể là sửa lỗi khó trong nhiều ngày, hoặc chỉ là cập nhật định dạng. Squash có thể gom hàng chục commit thành một. Review, thiết kế, hỗ trợ vận hành và trao đổi với người dùng có thể không xuất hiện trong thống kê tác giả.

Vì vậy, nên dùng shortlog làm điểm bắt đầu cho danh sách ghi nhận đóng góp, không làm bảng xếp hạng năng suất. Đối chiếu pull request, tài liệu và phản hồi của nhóm để bổ sung người tham gia chưa được phản ánh đầy đủ.

6. Checklist trước khi gửi danh sách release

• Phạm vi commit và chính sách tính merge được ghi rõ.
• Ánh xạ danh tính được người liên quan xác nhận và review.
• Bot, author và committer không bị trộn thành một khái niệm.
• Email không cần thiết được bỏ khỏi bản gửi công khai.
• Danh sách được kiểm tra cùng pull request và hoạt động ngoài commit.

Một báo cáo tốt giúp ghi nhận đúng người và giải thích được cách tạo dữ liệu. Giá trị của shortlog nằm ở khả năng tổng hợp để kiểm tra, không ở việc biến lịch sử Git thành điểm số con người.