Giao diện
Quy trình Git
Đặt tên
Nhánh cắt từ master, không cắt từ nhánh môi trường.
<type>/<issue>-<mô-tả-ngắn> features/251-setup-mobile-codebase<issue> là số issue trên GitHub. Nhánh không có số issue bị từ chối.
[<issue>] <đổi cái gì> [251] pi_core: Result and PiFailure
[<issue>-<sub>] <đổi cái gì> cho sub-issueGọn lại còn 1–3 commit trước khi mở pull request.
Promote
Ba luật tuyệt đối:
- Không bao giờ cherry-pick.
- Không bao giờ squash-merge.
- Nhánh môi trường không merge vào nhau.
Đơn vị được promote là một nhánh, không phải một commit. Cherry-pick làm mất quan hệ cha con nên lần merge sau sẽ xung đột hoặc âm thầm bỏ sót thay đổi.
staging được dựng lại khi cần (cho phép force-push). dev và masterkhông bao giờ force-push.
Migration
Migration là forward-only. Một file đã merge thì không bao giờ sửa — kể cả sửa comment, vì nó có thể đã chạy ở một môi trường nào đó.
Số migration phải duy nhất trên toàn repo, không chỉ trong nhánh của bạn. Hai nhánh cùng chọn một mốc thời gian là xung đột lúc merge, và tệ hơn là xung đột lúc deploy.
Đã có một ngoại lệ được duyệt: gộp các migration chưa từng lên môi trường nào thành ít file hơn trước khi phát hành. Một file đã tới nhánh môi trường thì luật forward-only áp lại ngay.
Quality gate
Gate đầy đủ tốn hơn 2,5 giờ runner, nên nó không chạy trên mọi pull request:
| Khi nào | Chạy gì |
|---|---|
PR vào master | Gate phát hành: guards + các job của area bị đổi |
PR vào dev, push thường | Không chạy gì ở đây |
| Chạy tay | Đúng các area được tick trong form |
Area được suy ra từ đường dẫn file đã đổi (scripts/ci/changed-areas.mjs), và bộ lọc đó có self-test riêng. Lượt chạy cũ của cùng pull request bị huỷ khi có push mới — trừ khi nó đã gần xong.
app-sale đang tạm dừng: thay đổi chỉ trong code/apps/app-sale/ không khởi động job mobile.
Kế hoạch và bằng chứng
Việc lớn chạy theo đợt (docs/implementation-plans/<đợt>/): mỗi đợt có sổ trạng thái, một README bằng chứng cho mỗi task, và một handoff.md.
Bằng chứng ghi SHA, lệnh đã chạy, mã thoát, số đếm — không commit log thô hay file kết quả.
Sau khi merge, code là nguồn sự thật: không test hay module nào được đọc file kế hoạch hay ghim con số lấy từ dữ liệu kế hoạch.
Nguồn: docs/technical/11-git-workflow.md, docs/technical/22-plans-evidence-tests.md, docs/contracts/ci-quality-gate.md, CLAUDE.md. Trang viết tay — xem mức độ tin cậy.