Release & phiên bản docs

Dùng Changesets. Các package @tasco/* đi lockstep (fixed), publish lên GitLab Package Registry (access: restricted). Tài liệu đi theo major: mỗi major một đường dẫn /vN/ cố định — xem Tài liệu theo phiên bản.

Quy trình hằng ngày

Mỗi MR có thay đổi ảnh hưởng package phải kèm changeset:

pnpm changeset
# chọn package + mức bump (patch/minor/major); major = breaking

File .md sinh ra trong .changeset/ commit cùng MR. AI (Claude Code) thì viết thẳng file .changeset/<slug>.md, không chạy lệnh tương tác.

Viết changeset

Nội dung changeset là thứ team sản phẩm đọc ở Changelog — trang đó gộp CHANGELOG.md của mọi package và hiện luôn các changeset chưa phát hành ở mục "Sắp phát hành".

• Dòng đầu là một câu nói thay đổi gì với người dùng framework, không phải việc đã làm trong code.
• Gạch đầu dòng tiếp theo: API mới hoặc đổi (tên prop, sự kiện, biến), hành vi khác trước, việc app cần làm.
• Breaking thì ghi rõ cách sửa hoặc link mục Migration.
• Một changeset chạm nhiều package thì liệt kê đủ package trong frontmatter — Changelog tự gộp thành một mục.

Thay đổi	Mức
Sửa lỗi, sửa tài liệu trong package, JSDoc	patch
Thêm component, prop, composable, token, export	minor
Đổi hoặc xoá API công khai, đổi hành vi mặc định	major (cần RFC Accepted)

Cadence & channels

• latest: release ổn định theo cadence cố định (vd 2 tuần/lần).
• beta / next: bản prerelease (x.y.z-beta.N) để team sản phẩm test trước. Ví dụ dưới đây dùng beta.

Mọi bản, kể cả beta, phát hành bằng version MR: MR chỉ chứa kết quả pnpm changeset version, merge vào main thì job release publish (xem Pipeline). Không cần publish từ máy cá nhân.

Bản ổn định

git switch -c chore/version-packages
pnpm changeset version       # bump version (lockstep) + CHANGELOG, xoá các file changeset
git add -A                   # gồm CHANGELOG mới của package lần đầu phát hành
git commit -m "chore(release): @tasco/* x.y.z"

Bản beta

Khi repo ở pre mode (có .changeset/pre.json), changeset publish tự publish lên dist-tag beta, CI không cần cấu hình riêng.

1. Vào beta: một version MR vừa bật pre mode vừa bump version.

   git switch -c chore/version-packages
   pnpm changeset pre enter beta
   pnpm changeset version       # x.y.z-beta.0; giữ file changeset, ghi id của chúng vào pre.json
   git add -A
   git commit -m "chore(release): @tasco/* x.y.z-beta.0"

2. Sửa lỗi trong beta: MR thường kèm changeset như mọi khi. Cần bản beta mới thì mở version MR chỉ chạy pnpm changeset version (ra beta.1, beta.2…).

3. Lên latest khi đạt tiêu chí promote: version MR chạy pnpm changeset pre exit rồi pnpm changeset version. Kết quả là x.y.z, pre.json và các file changeset bị xoá.

Đừng thêm --tag beta vào changeset publish: ở pre mode changesets dừng với lỗi Releasing under custom tag is not allowed in pre mode.

Pipeline (CI)

.gitlab-ci.yml ở root:

• quality (mọi nhánh): pnpm lint, pnpm typecheck, pnpm test, pnpm test:scripts, pnpm build, kiểm tra tài liệu — chi tiết ở CI/CD của core.
• release (nhánh main): scripts/release-guard.mjs quyết định có publish không, rồi build các package và chạy pnpm changeset publish. CI publish các package có version chưa có trên registry.

Job release chạy trên mọi commit main nhưng chỉ publish ở commit version, tức commit không còn changeset nào chưa version:

• Bản thường: changeset version đã xoá hết file changeset.
• Pre mode: mọi file changeset đều đã có id trong pre.json.

Commit khác (MR tính năng, docs) được bỏ qua, lý do ghi trong log job. Không có cổng này thì package mới merge trước khi version bị publish ngay, như @tasco/ai@1.3.0 và @tasco/mcp@0.0.0 ngày 23/07/2026.

Nếu main có thêm changeset trong lúc version MR chờ merge, job cũng bỏ qua publish: chạy lại pnpm changeset version trên main mới nhất rồi merge.

Chi tiết cấu hình registry/token (instance vs project endpoint, các gotcha 401): xem Cấu hình .npmrc.

Breaking change

• Bump major + viết mục Migration Guide tương ứng.
• Ưu tiên phát hành qua beta (mục Bản beta) để team sản phẩm migrate sớm.

Vai trò trong validate qua beta/next

• Ai bump: Maintainer core team, kích hoạt thủ công khi một MR T2/T3 (xem RFC Process cho định nghĩa tầng) quan trọng vừa merge vào main và cần test rộng trước cadence release chính thức. Gắn nhãn needs-beta-validation lên MR/issue theo dõi — không tự động hoá theo mọi merge để tránh spam registry.
• Ai test: team sản phẩm bị ảnh hưởng trực tiếp (được nêu trong RFC/MR hoặc comment core team) — bump dist-tag beta trong repo sản phẩm của họ, test trên staging.
• Tiêu chí promote lên latest:
  1. ≥1 team sản phẩm khác đội đề xuất xác nhận test OK trên beta (comment trên MR/issue theo dõi).
  2. Không có bug report mới trong ≥3 ngày làm việc kể từ lần publish beta gần nhất.
  3. Nếu breaking: Migration Guide đã có, ≥1 team migrate thử thành công.
  4. Core team Maintainer mở version MR thoát pre mode (bước 3 mục Bản beta).

Tài liệu theo phiên bản

Đơn vị phiên bản của docs là major (RFC 0003): trong một major, minor chỉ thêm tính năng tương thích ngược nên một bản docs đủ dùng. Không có docs riêng cho 1.x — team còn ở 1.x nâng cấp theo Migration v1 → v2.

Đường dẫn	Build từ	Trạng thái
/v2/	main	Bản mới nhất; / chuyển hướng về đây
/v3/	main khi 3.0 ra mắt	Lúc đó /v2/ build từ nhánh release/2.x

• Đường dẫn cố định: template CLI, CLAUDE.md của sản phẩm, MCP trỏ /v2/… và vẫn đúng sau khi 3.0 ra mắt.
• Đổi URL trong một major: thêm dòng vào docs/deploy/_redirects, giữ ít nhất tới hết major.
• docs/deploy/versions.json (deploy ở gốc site) liệt kê các bản docs. Hiện chỉ có /v2/ nên nhãn phiên bản trên nav là mục tĩnh; khi có bản thứ hai, menu phiên bản và banner "bản cũ" đọc file này lúc chạy để bản cũ không phải build lại.
• Docs đi trước bản phát hành: docs build từ main, nên có thể đã mô tả tính năng chưa lên registry. Mục "Sắp phát hành" của Changelog liệt kê các thay đổi đó; mục docs mô tả API mới gắn nhãn từ x.y — xem Viết tài liệu › API mới trong một major.

Khi đã có bản docs của major cũ

Cloudflare Pages thay toàn bộ site mỗi lần deploy, nên job deploy phải ghép đủ mọi phiên bản:

1. Push vào nhánh duy trì release/<major cũ>.x: build docs thành artifact v<major cũ>/ (GitLab giữ artifact mới nhất của nhánh), rồi kích hoạt pipeline main.
2. Pipeline main build bản mới, tải artifact mới nhất của nhánh duy trì qua API artifact của GitLab.
3. Ghép các bản, versions.json, _redirects thành một thư mục rồi deploy. Không tải được bản cũ thì job dừng — không deploy site thiếu phiên bản.

Phần ghép này chưa có trong .gitlab-ci.yml vì hiện chỉ có /v2/; làm cùng lúc phát hành 3.0.

Checklist phát hành major mới

Trước version MR:

• [ ] Mọi thay đổi breaking có RFC Accepted, changeset major và mục trong trang Migration.
• [ ] Đã phát hành ít nhất một bản beta và đạt tiêu chí promote.

Tách nhánh cho major cũ (ví dụ đang lên 3.0):

• [ ] Tạo nhánh release/2.x từ commit version cuối của 2.x — tìm commit chore(release): @tasco/* 2.… trong lịch sử main (remote chưa có tag phát hành).
• [ ] Bảo vệ release/2.x như main; sửa docs hoặc vá lỗi bản 2.x thì mở MR vào nhánh này.
• [ ] Nhánh release/2.x giữ nguyên base: '/v2/'.

Trên main:

• [ ] docs/.vitepress/config.ts: base: '/v3/', nhãn phiên bản trên nav.
• [ ] docs/deploy/versions.json: thêm v3.x là latest, v2.x bỏ latest.
• [ ] docs/deploy/_redirects: / chuyển về /v3/.
• [ ] .gitlab-ci.yml: bước ghép artifact của release/2.x vào job deploy (mục trên).
• [ ] Template CLI (README.md, CLAUDE.md, .mcp.json): link docs trỏ /v3/, ghim @tasco/mcp@3 — test của @tasco/cli fail ở version MR nếu còn major cũ.

@tasco/mcp tự trả link theo base mới của config docs, không phải sửa.

Sau phát hành:

• [ ] Mở /v2/ và /v3/ trên site thật, kiểm tra menu phiên bản và chuyển hướng /.
• [ ] Thông báo team sản phẩm kèm link Migration.