Files
poli0981andClaude Opus 5.5 7bcbcf59dd docs: maintenance mode — policy, triage bot, issue forms, status badge, docs for 2.3.0 (#139)
* docs: maintenance mode — policy, triage bot, issue forms, status badge, docs for 2.3.0

From v2.3.0 the project takes no new features (CONTRIBUTING.md, in Vietnamese and
English). Accepted: scheduled dependency updates; security fixes (High/Critical
advisories, runtime vulnerabilities); major language/runtime/framework upgrades; bug
fixes including UI/UX and accessibility; language fixes.

- .github/workflows/triage.yml + scripts/triage.mjs (unit-tested): an issue or pull
  request whose title or label asks for a feature is labelled enhancement + out-of-scope,
  answered in both languages and closed (issues as "not planned"). The owner's items, bots,
  `maintenance-exception` and anything the owner does are left alone. It runs on
  pull_request_target but checks out only that one script from the default branch, never a
  pull request's code; workflow_dispatch is a dry run.
- Issue forms: blank issues off, questions and ideas to Discussions, security to the
  private policy; a new language-problem form; the bug form no longer claims the site's
  report button fills it (those reports go to a private repository). The pull request
  template asks which of the five kinds of change it is.
- README: a maintenance-mode badge and a Status section; the admin paragraph describes
  auto-publish. SECURITY.md: High/Critical fixes ship out of schedule; the age-check
  answer is local storage only.
- Docs: decisions D21–D24, maintenance policy and cadence (17 §0, QODANA_TOKEN rotation),
  roadmap frozen, CI (Qodana, whole-tree licences, triage, merge rules), architecture
  tree, the Workers Builds deploy command, licence notes without the stale
  license-checker/GSAP lines.
- CHANGELOG [2.3.0]; sonar.projectVersion 2.3.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: link #138 in the 2.3.0 changelog

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: album labels come from both language entries

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(ci): triage without a checkout, and linear title patterns

SonarCloud and Qodana on #139:
- githubactions:S7631 flags any checkout in a pull_request_target workflow, even of the
  default branch. The workflow now reads scripts/triage.mjs from the default branch through
  the API and imports it from a data: URL — nothing is checked out at all.
- javascript:S8786: `\s+a?\s*` let two quantifiers compete for the same spaces. The title
  is trimmed once and the patterns are written so no two quantifiers overlap.
- Qodana RegExpRedundantEscape: the bot check is `endsWith("[bot]")`, no regex.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 08:48:09 +07:00

8.0 KiB
Raw Permalink Blame History

poli0981.dev — Documentation Suite

  • Phiên bản suite: v2.0 · Ngày: 2026-10-24 (v1.0: 2026-07-17)
  • Repo: poli0981/poli0981-dev (public từ 10/2026) · nội dung: poli0981/content (submodule src/content) · Domain: poli0981.dev
  • Lịch sử thay đổi theo phiên bản: CHANGELOG.md ở gốc repo.
  • Ngôn ngữ tài liệu: tiếng Việt (thuật ngữ kỹ thuật giữ tiếng Anh). Riêng 12_LEGAL/ soạn song ngữ EN/VI vì là văn bản sẽ render trên site.
  • Tài liệu gốc: poli0981.dev_proposal.md (bản đề xuất v0.1, đã được duyệt).

Danh sách file

# File Nội dung
00 00_INDEX.md File này — mục lục + nhật ký quyết định
01 01_PRD.md Mục tiêu, phạm vi, yêu cầu, bảng truy vết requirement
02 02_ARCHITECTURE.md Stack, cấu trúc repo, rendering, i18n, wrangler, ADR
03 03_DESIGN_SYSTEM.md Token màu/chữ/spacing, motion, component inventory
04 04_CONTENT_MODEL.md Content Collections, schema, quy trình viết, EXIF
05 05_SITEMAP_UX.md Route map, wireframe từng trang, legal gate, mobile nav
06 06_SECURITY.md Headers/CSP, form, rate limit, secrets, supply chain
07 07_CLOUDFLARE_SETUP.md Hướng dẫn set Cloudflare từng bước
08 08_CI_CD.md Workflows, permissions, deploy, Dependabot, hooks
09 09_ERROR_PAGES_OFFLINE.md 404/403/429/5xx/offline + cách test
10 10_BUG_REPORT_PIPELINE.md Console capture → GitHub Issue + Discord
11 11_WIDGETS_INTEGRATIONS.md YouTube/Steam/GitHub widgets, cron worker, KV
12 12_LEGAL/ 5 văn bản song ngữ (xem dưới)
13 13_SEO_RSS_OG.md Meta, hreflang, sitemap, RSS, OG image, AI crawlers
14 14_PERF_BUDGET.md Ngân sách hiệu năng + kỷ luật islands
15 15_ROADMAP.md P0 spikes, phase P1–P4, launch checklist
16 16_COST.md Chi phí chốt + ngưỡng cần theo dõi
17 17_MAINTENANCE.md Lịch bảo trì, update playbook, backup

12_LEGAL/: TERMS_OF_USE.md · PRIVACY_POLICY.md · DISCLAIMER.md · THIRD_PARTY_NOTICES.md · CONTENT_LICENSE.md — bản nháp gốc (07/2026). Văn bản đang hiệu lực là legal/*.md trong repo poli0981/content (render ở /legal/*); sửa ở đó, không sửa ở đây. Hai trang thêm sau (ai-usage, accessibility) chỉ có ở repo content, không có bản nháp tại đây.

Nhật ký quyết định (chốt 2026-07-17, cập nhật 2026-11-10)

# Quyết định Chọn
D1 Framework/hosting Astro 7 + Svelte 5 islands, Cloudflare Workers + Static Assets
D2 Quy trình viết Markdown + Git (repo poli0981/content). Từ 10/2026 thêm admin tự viết ở admin.poli0981.dev (soạn/sửa → commit repo content; Xuất bản → workflow content-bump.yml mở PR bump submodule + auto-merge). Không Keystatic/CMS bên thứ ba
D3 Q&A FAQ tĩnh + liên hệ qua social/contact@ — không form, không D1
D4 Ngôn ngữ VI (mặc định, không prefix) + EN (/en/)
D5 Bình luận blog Tắt (không Giscus)
D6 Legal canonical Trên site tại /legal/*; repo public mirror poli0981/legal = tuỳ chọn sau
D7 Giấy phép Code GPL-3.0 · Nội dung All Rights Reserved
D8 Error pages Tự phục vụ từ app (không mua zone Pro)
D9 API ngoài Không weather/map; widget YouTube + Steam + GitHub qua cron worker
D11 Email Google Workspace (MX Google), một hộp thư + alias theo chủ đề (07 §11). Không Cloudflare Email Routing
D12 Chống bot Cổng Turnstile trước mọi trang, vé 48 giờ (06 §3b); bot đã xác thực đi thẳng nhờ Transform Rule x-verified-bot
D13 Rate limit WAF rule (edge) → Workers Rate Limiting: RL_SITE toàn site 100/10s → bindings theo nhóm /api (06 §2, 07 §6) thay bộ đếm KV
D14 Analytics Cloudflare Web Analytics, snippet thủ công chỉ ở bản build production (07 §12)
D15 Admin admin.poli0981.dev sau Cloudflare Access + Worker tự kiểm JWT (≤ 24 giờ, email phải có trong ADMIN_EMAILS — thiếu là từ chối); token GitHub chỉ ghi repo content; ảnh → Images binding → R2; mọi thao tác ghi audit log (06 §9)
D10 Data services KV (cache widget + ảnh widget mirror cho /ext-img, denylist một khoá, audit log admin) + R2 poli0981-media cho ảnh upload qua admin (từ 10/2026; AVIF/WebP sinh một lần lúc upload, phục vụ qua /media, cache 1 năm). Không D1. Ảnh build-time cũ vẫn ở src/assets/
D16 Palette & theme (10/2026) Glacier Teal (xanh đêm + teal) thay palette ấm; theme mặc định theo hệ điều hành, nút 3 trạng thái hệ thống/sáng/tối (03 §2, §6)
D17 Toolchain (10/2026) Node 26 · TypeScript 7 (tsc kiểm kiểu) chạy song song TypeScript 6 (astro check, typescript-eslint, svelte2tsx cần JS API) · test bằng node:test (không thêm deps) · SonarCloud phân tích qua CI (08 §0)
D18 Báo lỗi (10/2026) Issue tạo ở repo private poli0981/site-reports (repo site đã public) — 10 §4
D19 Phát hành Tag vX.Y.Z có ký GPG + GitHub Release + CHANGELOG.md; deploy vẫn là "merge main" (08 §8)
D20 Trợ năng (11/2026, v2.2.0) Mục tiêu WCAG 2.2 AA — kim chỉ nam, không tự nhận đã được kiểm định. Tuyên bố cho khách ở /legal/accessibility (song ngữ, repo content); ACCESSIBILITY.md ở root là bản của repo kèm ghi chú cho người sửa code (trang site thắng nếu lệch). Rào cản báo về accessibility@ hoặc nút "Báo lỗi". Cổng tự động: npm run test:a11y (axe-core + bàn phím + reflow + forced-colors, Playwright lái Chrome có sẵn) chạy trong check bắt buộc build (08 §0, checklist ở 03 §8) — ngoại lệ có chủ đích của D17 "không thêm deps cho test"
D21 Chế độ bảo trì (11/2026, v2.3.0) Không thêm tính năng mới. Chỉ nhận: deps định kỳ · vá bảo mật (High/Critical, lỗ hổng runtime) · nâng cấp lớn ngôn ngữ/runtime/framework · sửa lỗi (UI/UX, a11y) · sửa lỗi ngôn ngữ. Bot triage.yml gắn enhancement + out-of-scope và đóng đề xuất tính năng; ngoại lệ = nhãn maintenance-exception (CONTRIBUTING.md, 17 §0)
D22 Nhãn nội dung & tuổi (11/2026) contentWarning từ danh sách cố định 11 nhãn (src/lib/content-labels.ts) cho blog/truyện/album/từng ảnh + ageRating 13+/16+/18+. Banner; ảnh mờ bằng CSS (:has(), chạy khi tắt JS); hỏi tuổi bằng <dialog> gốc, không tự bật, câu trả lời chỉ ở localStorage ageGate (mốc tuổi, không ngày sinh) — Privacy §6 (04 §2)
D23 Xuất bản tự động (11/2026) Mỗi lần lưu/xoá trong admin tự dispatch content-bump.yml; build ghi __CONTENT_COMMIT__ ⇒ /api/health có version.content, admin phân biệt "đã merge" với "đã lên web". Điều kiện: Workers Builds deploy main (07 §9)
D24 Chất lượng (11/2026) Thêm Qodana (Ultimate, Qodana for JS, ngưỡng 0) cạnh SonarCloud. License: kiểm toàn bộ package-lock.json, ngoại lệ theo gói có lý do (scripts/license-policy.mjs) — license audit của Qodana cần Ultimate Plus nên không dùng (08 §0)

Cách dùng suite

  1. 15_ROADMAP.md có trạng thái từng phase (P0–P3 đã xong, P4 launch đang chạy) và hướng đi tiếp.
  2. 07_CLOUDFLARE_SETUP.md làm một lần khi mua domain, tick checklist cuối file.
  3. Mỗi file có mục Trạng thái/Checklist riêng khi áp dụng — suite này là nguồn sự thật, cập nhật khi quyết định thay đổi.
  4. Lưu ý chung: phiên bản package ghi trong suite là bản đang dùng tại 2026-10-24 (02 §2); package.json + lockfile mới là nguồn sự thật.