GitLab MR Browser Extension¶
Extension dành cho reviewer muốn đọc Markdown Before/After và so sánh diagram ngay trong tab Changes của GitLab merge request.
Trước khi bắt đầu¶
Bạn cần:
- Trình duyệt Chromium.
- Package extension do dự án phát hành.
- Quyền mở merge request trên GitLab HTTPS.
- Địa chỉ Code To UML và token truy cập.
Nếu dùng package unpacked, giải nén package, mở trang quản lý extension, bật Developer mode rồi chọn Load unpacked.
Mở extension options:
- Nhập địa chỉ HTTPS của Code To UML, không kèm endpoint path.
- Nhập token truy cập.
- Chọn Test.
- Lưu khi kiểm tra thành công.
Token được lưu trong vùng dữ liệu riêng của extension và chỉ được dùng khi gọi Code To UML. Extension không yêu cầu GitLab personal access token và không chèn token vào trang GitLab.
Review một merge request¶
- Đăng nhập GitLab và mở merge request.
- Chuyển tới tab Changes.
- Bấm biểu tượng Code To UML để cho phép extension chạy trên tab hiện tại.
- Chọn View preview before/after để đọc toàn bộ file Markdown ở hai phía.
- Tại diagram thay đổi, chọn View diagram diff.
- Với diagram chỉ có ở một phía, chọn View added hoặc View removed.
- Chọn cách so sánh phù hợp rồi đóng panel khi hoàn tất.
Kết quả mong đợi: nút xem xuất hiện gần fence thay đổi; extension chỉ gửi mã sơ đồ tới Code To UML khi bạn mở bảng so sánh.
Tab mới hoặc một địa chỉ GitLab khác cần được kích hoạt lại bằng biểu tượng extension. Quyền này là tạm thời cho tab hiện tại.
Chọn cách so sánh¶
| Chế độ | Cách hiển thị | Phù hợp khi |
|---|---|---|
| Before / After | Chỉ xem một phiên bản | Cần kiểm tra nhanh mã đã thêm hoặc xóa |
| Side by side | Hai sơ đồ đặt cạnh nhau | Cần so sánh cấu trúc tổng thể |
| Onion skin | Hai hình chồng lên nhau | Cần thấy vị trí hoặc hình dạng thay đổi nhỏ |
Onion skin hữu ích nhất khi hai sơ đồ có kích thước gần nhau. Nếu hình chênh lệch lớn, dùng Side by side để tránh hiểu nhầm.
Giúp extension ghép đúng diagram¶
Thêm diagram-id vào dòng mở fence để extension nhận ra cùng một sơ đồ ở hai
phiên bản, kể cả khi bạn đổi vị trí, title hoặc loại sơ đồ:
```plantuml diagram-id=checkout-sequence title="Checkout sequence"
@startuml
Customer -> Checkout: Pay
@enduml
```
ID phải dài từ 1 đến 64 ký tự, bắt đầu bằng chữ hoặc số và chỉ chứa chữ thường,
số, ., _ hoặc -. Mỗi ID chỉ được xuất hiện một lần trong cùng file. Hãy giữ
nguyên ID khi sửa mã, đổi title, di chuyển fence hoặc đổi loại sơ đồ.
Extension hiển thị cảnh báo nếu ID sai định dạng, bị trùng hoặc chỉ có ở một
phía. Tài liệu cũ không có diagram-id vẫn được ghép theo title, loại sơ đồ và
thứ tự xuất hiện, nhưng có thể kém chính xác khi nhiều sơ đồ giống nhau bị đổi
vị trí. Hai ID hợp lệ khác nhau không được ghép thành một cặp.
title tiếp tục được dùng làm tên hiển thị; diagram-id chỉ giúp review thay
đổi và không được gửi tới Code To UML để render.
Dùng options trong diagram¶
Extension hiện chưa áp dụng tùy chọn trên dòng mở fence. Hãy đặt directive trong phần thân sơ đồ:
```mermaid diagram-id=checkout-flow title="Checkout flow"
%%krokup {theme=dark scale=1.5}
flowchart LR
Cart --> Payment
```
Xem Diagram Customization để biết cú pháp
%%krokup.
Quyền truy cập và dữ liệu¶
- Extension chỉ chạy trên tab GitLab mà bạn kích hoạt bằng biểu tượng Code To UML.
- Extension dùng phiên đăng nhập GitLab hiện tại để đọc nội dung bạn đã có quyền xem; không yêu cầu personal access token.
- Token Code To UML không được chèn vào trang GitLab.
- Mã sơ đồ chỉ được gửi để render khi reviewer mở bảng so sánh.
- Quyền sử dụng Pydia vẫn phụ thuộc vào cấu hình của hệ thống.
Xóa token trong options trước khi bàn giao máy hoặc gỡ extension.
Xử lý sự cố¶
| Hiện tượng | Cách xử lý |
|---|---|
| Không thấy nút xem | Mở tab Changes, bấm lại biểu tượng extension và tải lại trang nếu cần |
| Markdown preview lỗi | Đăng nhập lại GitLab rồi tải lại merge request |
| Diagram không ghép đúng | Thêm diagram-id duy nhất và giữ nguyên ID ở hai phiên bản |
| Cảnh báo ID sai hoặc trùng | Dùng 1–64 ký tự hợp lệ và bảo đảm mỗi ID chỉ xuất hiện một lần trong file |
| Cảnh báo ID chỉ có ở một phía | Thêm cùng diagram-id vào phiên bản còn lại nếu đó là cùng một sơ đồ |
401 từ Code To UML |
Mở options, nhập lại token và chạy Test |
| Không kết nối Code To UML | Kiểm tra địa chỉ HTTPS; nếu Test vẫn lỗi, liên hệ quản trị viên |
| Fence params bị bỏ qua | Chuyển tùy chọn vào directive %%krokup trong phần thân |
| Onion skin khó đọc | Chuyển sang Side by side |
Thông tin build, test, manifest và invariant dành cho contributor nằm trong Developer Guide.