Skip to content

Release & phiên bản docs ​

Dùng Changesets. Các package @tasco-fe/* đi lockstep (fixed), publish lên npmjs.org (access: public). 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:

bash
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 đổiMức
Sửa lỗi, sửa tài liệu trong package, JSDocpatch
Thêm component, prop, composable, token, exportminor
Đổi hoặc xoá API công khai, đổi hành vi mặc địnhmajor (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 ​

bash
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-fe/* 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.

    bash
    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-fe/* 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) ​

Jenkinsfile ở root (job nhánh main; các nhánh khác dùng Jenkinsfile.mr, chỉ chạy quality):

  • 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-fe/ai@1.3.0 và @tasco-fe/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 token publish và các gotcha (402, 401, không gỡ được bản đã publish): xem Cấu hình .npmrc và publish lên npmjs.

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ẫnBuild từTrạng thái
/v3/mainBản mới nhất; / chuyển hướng về đây
/v2/nhánh release/2.xBản 2.x, build lại cùng mỗi lần deploy main
  • Đường dẫn cố định: template CLI, CLAUDE.md của sản phẩm, MCP trỏ /v<major>/… và vẫn đúng sau khi major mới 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. Nhãn phiên bản trên nav là mục tĩnh trong docs/.vitepress/config.ts (kèm link sang bản cũ); khi cần, menu phiên bản và banner "bản cũ" đọc file này lúc chạy.
  • 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. scripts/build-docs-site.sh (gọi từ Jenkinsfile stage deploy:pages) làm việc này:

  1. Build docs của checkout hiện tại vào site/v3/.
  2. Checkout origin/release/2.x (nhánh duy trì) vào một thư mục tạm, pnpm install --frozen-lockfile, build docs vào site/v2/ (tuần tự để pod không bị OOMKilled).
  3. Chép _redirects và versions.json ra gốc site/ rồi deploy. Không dựng được bản cũ thì script dừng — không deploy site thiếu phiên bản.

Sửa docs hoặc vá lỗi bản 2.x thì mở MR vào release/2.x, rồi chạy lại pipeline main để site build lại /v2/. Nhánh release/2.x được tách từ commit main cuối cùng còn ở 2.x và đã có base: '/v2/' (không phải commit chore(release): @tasco/* 2.0.0, vì khi đó docs chưa theo cấu trúc RFC 0003).

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):

  • [x] Tạo nhánh release/2.x (xem mục trên về commit gốc).
  • [ ] 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/.
  • [x] Jenkinsfile: bước ghép docs của release/2.x vào job deploy (scripts/build-docs-site.sh).
  • [ ] Template CLI (README.md, CLAUDE.md, .mcp.json): link docs trỏ /v3/, ghim @tasco-fe/mcp@3 — test của @tasco-fe/cli fail ở version MR nếu còn major cũ.

@tasco-fe/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.