Tasco Framework

Giao diện

Git workflow ​

Quy trình làm việc với repo core trên GitLab: nhánh, commit, merge request và các thiết lập của project.

1. Lấy code ​

bash
git clone ssh://git@gitlab.dnpwater.vn:2222/tasco/web-framework-core.git

Cài đặt và chạy: Thiết lập monorepo. main là nguồn phát hành — không push hay force-push thẳng lên main.

2. Branch model (trunk-based) ​

main ────●────●────●────●───▶   (luôn xanh, là nguồn release)
          \        /
  feat/*    ●──●──●   (nhánh ngắn, merge qua MR)
  • Nhánh tính năng: feat/<scope>, sửa lỗi: fix/<scope>, tài liệu: docs/<scope>.
  • Nhánh ngắn ngày, rebase theo main thường xuyên, merge qua Merge Request.
  • Không commit thẳng lên main.
bash
git switch -c feat/use-table-filters
# ... code ...
pnpm lint && pnpm typecheck && pnpm build
pnpm changeset            # nếu có đổi package
git push -u origin feat/use-table-filters
# mở Merge Request trên GitLab

3. Commit convention ​

Dùng Conventional Commits, mô tả bằng tiếng Việt: feat:, fix:, docs:, chore:, refactor:, test:. Scope theo package: feat(ui): CForm expose API của form qua template ref, fix(composables): ….

Conventional Commits là cho lịch sử git. Bump version + changelog do Changesets quyết định (xem Release). Mỗi MR đổi package bắt buộc kèm một changeset.

4. Bảo vệ nhánh main (GitLab settings) ​

  • Settings → Repository → Protected branches: main = Maintainers push, no force-push.
  • Settings → Merge requests: bật Pipelines must succeed + All threads resolved.
  • Yêu cầu tối thiểu 1 approval cho MR.
  • Bật Code Owner approval (Settings → Merge requests → Merge request approvals) để file CODEOWNERS ở root repo thật sự chặn merge theo package — nếu không bật, file chỉ mang tính tham khảo. Owner trong CODEOWNERS hiện là placeholder (@team-ui-owners...), phải tạo group GitLab thật khớp tên trước khi bật rule này.

Quyền cho dev team sản phẩm đóng góp vào core ​

Team sản phẩm dev trên repo riêng — để mở MR vào core, cấp:

  • Developer trên project web-framework-core (không Maintainer).
  • Reporter ở group tasco nếu dev dùng PAT cá nhân để cài @tasco/* cho app sản phẩm. Cài chính monorepo core không cần token vì mọi @tasco/* là workspace package.

Dùng direct-branch, không fork: job CI ai-review/ai-eval cần biến bảo mật (ANTHROPIC_API_KEY, GITLAB_REVIEW_TOKEN) mà fork thường không kế thừa; team sản phẩm là nội bộ Tasco nên rủi ro thấp hơn mô hình fork công khai.

5. Biến CI/CD ​

Settings → CI/CD → Variables. Biến bí mật bật Masked; biến chỉ dùng trên main (publish, deploy) bật thêm Protected. Bảng đầy đủ từng biến dùng cho job nào: CI/CD của core › Biến CI/CD.

Pipeline chạy quality ở mọi nhánh (lint → typecheck → test → build → độ phủ tài liệu) và release, deploy:pages trên main — xem CI/CD của core.

6. Quy trình release ​

bash
# 1) Trên main đã gom đủ changeset → bump version + changelog:
git switch -c chore/version-packages
pnpm changeset version       # cập nhật version (lockstep) + CHANGELOG
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"
git push -u origin chore/version-packages
# 2) Merge MR này vào main → CI job `release` tự `changeset publish`.

Tag nên gắn theo version (Changesets/CI có thể tạo @tasco/...@x.y.z). Bản beta (pre mode) và điều kiện để job release publish: xem Release.

7. Repo team sản phẩm (riêng biệt) ​

Mỗi sản phẩm là repo riêng, không clone monorepo core:

bash
npx @tasco/cli tasco-orders     # đã có .gitlab-ci.yml + .npmrc
cd tasco-orders && git init && git add -A && git commit -m "chore: init"
git remote add origin ssh://git@gitlab.dnpwater.vn:2222/<group-sản-phẩm>/tasco-orders.git
git push -u origin main

CI của team sản phẩm cũng cần biến NPM_TOKEN để cài @tasco/* từ registry.

8. .gitignore ​

Đã loại trừ node_modules, dist, .nuxt, .output, .turbo, storybook-static, .vitepress/cache, .env* (giữ .env.example). Không commit secrets.

9. Checklist thao tác thủ công GitLab (làm 1 lần khi setup quy trình đóng góp) ​

Các mục dưới đây chỉ admin/Maintainer GitLab bật được qua UI Settings — không thể làm qua sửa file trong repo:

  1. Protected branches: xác nhận main chặn push trực tiếp, chỉ merge qua MR (mục 4).
  2. Merge request settings: bật "Pipelines must succeed", "All threads resolved" (mục 4).
  3. Merge request approvals: ≥1 approval + bật "Code Owner approval" — nếu không bật, CODEOWNERS (root repo) không chặn gì cả, chỉ mang tính tham khảo.
  4. Members: cấp Developer (project web-framework-core) + Reporter (group tasco) cho từng dev team sản phẩm tham gia đóng góp.
  5. CI/CD Variables: xác nhận NPM_TOKEN, ANTHROPIC_API_KEY, GITLAB_REVIEW_TOKEN đã Masked + Protected đúng scope (mục 5).
  6. Tạo GitLab group thật khớp tên dùng trong CODEOWNERS (thay các placeholder @team-ui-owners, @team-composables-owners, @team-theme-owners, @team-platform-owners, @team-ai-owners, @core-team) — làm trước mục 3.
  7. Tạo labels: rfc, contribution::t1-fix, contribution::t2-feature, contribution::t3-breaking, status::needs-rfc, status::good-first-contribution, status::declined, needs-beta-validation, feature-request.