Release và báo cáo

zenify release-note ghi metadata rủi ro cho từng thay đổi khi ship. zenify release-report gom các ghi chú đó thành một báo cáo rủi ro cho một release tag, đọc thẳng từ git.

Khi nào dùng

Bạn hiếm khi gõ zenify release-note tay. /znf:ship gọi lệnh này ở bước cuối, trước khi push branch, lấy giá trị từ ba tag rủi ro trong Brief của spec. Bạn chỉ chạy tay khi ship không có spec để lấy giá trị, hoặc khi đi đường không dùng workflow.

Chạy zenify release-report sau khi đánh tag release vYYMMDD.n trên main và trước khi deploy tag đó. Bản tuần là một tag, mỗi hotfix là một PR vào main rồi thêm một tag nữa, ví dụ v261028.0 rồi v261028.2.

Các bước

Từ một lần ship đến báo cáo release

Lệnh

zenify release-note

Cờ	Ý nghĩa
--slug	Slug của thay đổi. Bắt buộc.
--note	Mô tả một dòng.
--blast	Phạm vi ảnh hưởng. Mặc định unknown.
--db	Thay đổi DB. Mặc định N/A.
--rollback	Cách rollback. Mặc định revert PR.
--spec	Đường dẫn spec, tùy chọn.
--dir	Thư mục repo. Mặc định thư mục hiện tại.

zenify release-note --slug kit-docs-site --note "Site tài liệu VitePress" \
  --blast "zenify-kit" --db "N/A" --rollback "revert PR"

Thiếu --slug thì lệnh bỏ qua và không chặn ship. Commit lỗi cũng không chặn ship.

zenify release-report

Cờ	Ý nghĩa
--out-dir	Thư mục ghi báo cáo. Mặc định thư mục releases của knowledge store.
--workspace	Thư mục workspace. Mặc định thư mục hiện tại.
--no-fetch	Không fetch, dùng ref local.
--verbose	Hiện cả commit chore và chi tiết từng commit.

zenify release-report v261104.0

Mỗi repo được tính trên khoảng từ tag liền trước tới tag bạn truyền, kể cả tag hotfix: nếu giữa tuần có v261028.2 thì báo cáo v261104.0 bắt đầu từ v261028.2, nên một tuần có hotfix ra nhiều file báo cáo. Không truyền tag, lệnh lấy tag mới nhất trong cả workspace và chỉ báo cáo các repo mang tag đó: nếu hotfix chỉ tag be thành v261104.1 thì báo cáo v261104.1.md chỉ có be. Truyền tag thì repo không mang tag đó có dòng "chưa có tag" trong báo cáo. Repo không có tag release nào chỉ có dòng "chưa có tag" khi được ghim trong .zenify/release-repos.txt; ở chế độ tự dò, repo đó bị bỏ khỏi báo cáo. Không repo nào có tag thì lệnh báo ra stderr, không ghi file và kết thúc bình thường.

Kết quả

Artifact	Nội dung
Commit chore(release): note <slug>	Trailer gồm slug, mô tả, blast radius, DB, cách rollback, đường dẫn spec nếu có
<tag>.md	Báo cáo cho một tag, ví dụ v261104.0.md, ghi vào thư mục releases của knowledge store

Mỗi dòng trong báo cáo lấy metadata từ commit ghi chú của zenify release-note. Thay đổi có trong release nhưng chưa có trên staging được đánh dấu là regression, để bạn biết một hotfix chưa sync ngược.

Cắt release cho zenify-kit

Release của kit là một tag v* đẩy lên main: workflow release chạy GoReleaser, dựng binary cho 6 target, mở PR chore/tap-vX.Y.Z cập nhật Homebrew cask và Scoop manifest vào main (ruleset chặn push thẳng) rồi bật auto-merge cho PR đó, nên PR tự merge khi Zenie Review xanh. Chỉ role admin hoặc maintain của repo đẩy được tag v* (ruleset tag). Tag đẩy lên là đã release, không rút lại được, nên mọi việc kiểm phải xong trước khi tag.

Từ main tới binary trên máy teammate

1. Liệt kê thay đổi: git log --oneline <tag cuối>..origin/main. Với mỗi commit feat/fix, nêu trang trên site mô tả nó. Trang reference/** sinh tự động và đã được docs gen --check chặn trong CI; các trang concepts/, workflows/, guides/, getting-started/ viết tay và không có gate cơ học, nên đây là bước người phải làm. Skill hoặc agent mới cần đủ ba nơi: fragment trong internal/docsgen/catalog/{skills,agents}/<tên>.md, trang reference/** sinh lại, và ít nhất một liên kết từ trang viết tay (bảng skill ở Chọn workflow hoặc mục "Xem thêm" của trang concept).
2. Đóng khoảng trống trước khi tag: thiếu trang thì mở PR docs, merge, rồi mới tiếp. Trong PR đó viết mục ## vX.Y.Z cho bản sắp cắt vào Changelog: gạch đầu dòng tiếng Việt cho người dùng kit, không dán commit. Rule kit-release-docs trong knowledge store nhắc agent điều này mỗi khi sửa kit; hành vi bị bỏ (một bước, một cờ, một gate) phải xoá câu tương ứng trên site trong cùng PR.
3. Kiểm main: zenify docs gen --check khớp, npm run docs:build build xong, CI main xanh.
4. Đánh số: có feat → tăng minor (v0.23.0 → v0.24.0); chỉ fix → tăng patch.
5. Tag và đẩy: git tag vX.Y.Z origin/main && git push origin vX.Y.Z. Theo dõi gh run list --workflow release; gh release view vX.Y.Z phải có checksums.txt cùng 6 archive (3 OS × 2 arch), và PR chore/tap-vX.Y.Z đã mở với auto-merge bật; PR tự merge khi Zenie Review xanh, trước đó brew upgrade/scoop update vẫn ra bản cũ. PR do một GitHub App mở, vì org không cho GITHUB_TOKEN của Actions mở PR. Key của App là hai secret RELEASE_APP_CLIENT_ID và RELEASE_APP_KEY trong environment release: job chỉ đọc được hai secret này khi chạy từ tag v*, và chỉ role admin hoặc maintain đẩy được tag v*. Workflow chạy là bản ở commit mà tag trỏ tới, nên đừng gắn tag v* vào commit ngoài main: workflow ở commit đó đọc được key của App, mà App này cài trên mọi repo của org. Thiếu secret thì run đỏ ngay đầu, trước khi GoReleaser publish gì. Bước mở PR hoặc bật auto-merge lỗi thì run đỏ dù GitHub Release và binary đã ra: khi đó mở tay gh pr create --head chore/tap-vX.Y.Z --base main rồi merge. PR mở rồi mà quá 15 phút chưa merge thì xem check Zenie Review trên PR đó, rồi merge tay. Chạy lại run của cùng một tag thì xoá nhánh chore/tap-vX.Y.Z trước. Workflow release từ chối tag không có mục ## vX.Y.Z trong website/changelog.md, và dùng mục đó làm nội dung GitHub Release.
6. Phân phối: teammate chạy brew upgrade --cask zenify && zenify up --apply (hoặc zenify update). Skill mới tới máy qua zenify skills sync, hook mới qua zenify up.

Không tag khi còn khoảng trống docs

Tag là quyết định release của người, không của agent. Agent chuẩn bị PR docs và danh sách khoảng trống; lệnh git push origin vX.Y.Z do bạn chạy hoặc bảo agent chạy rõ ràng.

Lưu ý

zenify release-report chỉ đọc git, không tự sửa gì và không chặn deploy. Đây là artifact để bạn tự quyết định release có an toàn hay không.

Xem thêm

Changelog, /reference/cli/zenify_release-note, /reference/cli/zenify_release-report, ship: verify và mở PR