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>
This commit is contained in:
poli0981andClaude Opus 5.5 authored and GitHub committed 2026-11-21 08:48:09 +07:00
1 parent 484907439a
commit 7bcbcf59dd
20 files changed
+541 -23

No files matched your search

+7 -1
View File
@@ -7,7 +7,13 @@ body:
attributes:
value: |
Cảm ơn bạn đã báo lỗi. / Thanks for reporting.
Báo lỗi gửi từ nút "Báo lỗi" trên trang sẽ tự điền các mục dưới đây.
Nhanh hơn: nút "Báo lỗi" ngay trên trang gửi kèm trang và môi trường đang dùng (báo cáo đó đi
vào một repo riêng, không hiện ở đây). / Quicker: the "Report a problem" button on the page
itself sends the page and environment along (those reports go to a private repository and
do not show up here).
Dự án đang ở chế độ bảo trì: form này dành cho lỗi, không dành cho đề xuất tính năng — xem
CONTRIBUTING.md. / The project is in maintenance mode: this form is for bugs, not feature
requests — see CONTRIBUTING.md.
- type: textarea
id: description
attributes:
+13
View File
@@ -0,0 +1,13 @@
# Maintenance mode (CONTRIBUTING.md): issues are for bugs, accessibility and language problems.
# Questions and ideas go to Discussions; security problems are reported privately.
blank_issues_enabled: false
contact_links:
- name: Question or idea · Câu hỏi hoặc ý tưởng
url: https://github.com/poli0981/poli0981-dev/discussions
about: >-
The project is in maintenance mode and takes no new features — ask or talk ideas over in
Discussions. · Dự án đang ở chế độ bảo trì, không nhận tính năng mới — hỏi hoặc trao đổi
ý tưởng trong Discussions.
- name: Security vulnerability · Lỗ hổng bảo mật
url: https://github.com/poli0981/poli0981-dev/security/policy
about: Report it privately, never in a public issue. · Báo riêng, không mở issue công khai.
+46
View File
@@ -0,0 +1,46 @@
name: Lỗi ngôn ngữ / Language problem
description: >-
Lỗi chính tả gây hiểu nhầm, câu chữ không hợp văn hoá hay giọng địa phương (tiếng Việt hoặc tiếng
Anh). / A misleading typo, or wording that does not fit the culture or local voice (Vietnamese or
English).
title: "[language] "
labels: ["language"]
body:
- type: markdown
attributes:
value: |
Cảm ơn bạn! Mỗi báo cáo một chỗ (hoặc một nhóm chỗ cùng một lỗi). / Thanks! One report per
place, or per group of places with the same problem.
- type: input
id: page
attributes:
label: Trang / Page
description: Đường dẫn trang, hoặc file nếu bạn biết. / The page's URL, or the file if you know it.
placeholder: "https://poli0981.dev/blog/…"
validations:
required: true
- type: dropdown
id: language
attributes:
label: Ngôn ngữ / Language
options:
- Tiếng Việt / Vietnamese
- Tiếng Anh / English
validations:
required: true
- type: textarea
id: current
attributes:
label: Câu hiện tại / Current text
description: Chép nguyên văn. / Copy it exactly.
validations:
required: true
- type: textarea
id: suggestion
attributes:
label: Đề xuất sửa và lý do / Suggested wording and why
description: >-
Vì sao câu hiện tại gây hiểu nhầm hoặc không hợp? / Why is the current text misleading or a
poor fit?
validations:
required: true
+11
View File
@@ -2,6 +2,17 @@
<!-- One or two sentences. Link the issue if there is one. -->
## Kind of change
The project is in maintenance mode ([CONTRIBUTING.md](https://github.com/poli0981/poli0981-dev/blob/main/CONTRIBUTING.md)):
new features are not accepted, and a `feat:` pull request is closed automatically.
- [ ] Dependency update
- [ ] Security fix (High/Critical advisory, or a runtime vulnerability)
- [ ] Major language, runtime or framework upgrade
- [ ] Bug fix — including UI/UX and accessibility
- [ ] Language fix — a misleading typo, or wording that does not fit
## Checks
- [ ] `npm run format:check`, `npm run lint`, `npm run check`, `npm run typecheck`, `npm test`
+83
View File
@@ -0,0 +1,83 @@
name: Triage
# Maintenance mode (CONTRIBUTING.md): an issue or pull request asking for a new feature is
# labelled `enhancement` + `out-of-scope`, answered in both languages and closed. The rules
# live in scripts/triage.mjs (unit-tested); this only wires them to GitHub. The owner's own
# items, bots, and anything labelled `maintenance-exception` are left alone.
#
# pull_request_target runs with this repository's token, so it must never run a pull
# request's code. Nothing is checked out at all: the script reads scripts/triage.mjs from the
# default branch through the API and imports it from memory.
on:
issues:
types: [opened, reopened, edited, labeled]
pull_request_target:
types: [opened, reopened, edited, labeled]
# Dry run on main: classify a title and print the decision, writing nothing.
workflow_dispatch:
inputs:
title:
description: "Title to classify"
required: true
kind:
description: "issue or pull_request"
default: issue
permissions: {}
concurrency:
group: triage-${{ github.event.issue.number || github.event.pull_request.number || github.run_id }}
cancel-in-progress: false
jobs:
triage:
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
contents: read
issues: write
pull-requests: write
steps:
- name: Label and close feature requests
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
with:
script: |
const { data: file } = await github.rest.repos.getContent({
...context.repo,
path: "scripts/triage.mjs",
ref: context.payload.repository.default_branch,
});
const source = file.content.replaceAll("\n", "");
const { decide, closingComment, LABELS } = await import(
`data:text/javascript;base64,${source}`
);
if (context.eventName === "workflow_dispatch") {
const { title, kind } = context.payload.inputs;
const verdict = decide({ title, labels: [], author: "someone", association: "NONE" });
core.notice(`${kind} "${title}": ${verdict.action} (${verdict.reason})`);
return;
}
const item = context.payload.issue ?? context.payload.pull_request;
const kind = context.payload.pull_request ? "pull_request" : "issue";
const verdict = decide({
title: item.title,
labels: (item.labels ?? []).map((label) => label.name),
author: item.user.login,
association: item.author_association,
sender: context.payload.sender?.login,
owner: context.repo.owner,
state: item.state,
});
core.info(`#${item.number}: ${verdict.action} (${verdict.reason})`);
if (verdict.action !== "close") return;
const target = { ...context.repo, issue_number: item.number };
await github.rest.issues.addLabels({ ...target, labels: [LABELS.feature, LABELS.closed] });
await github.rest.issues.createComment({ ...target, body: closingComment(kind) });
if (kind === "pull_request") {
await github.rest.pulls.update({ ...context.repo, pull_number: item.number, state: "closed" });
} else {
await github.rest.issues.update({ ...target, state: "closed", state_reason: "not_planned" });
}
+76 -1
View File
@@ -7,6 +7,80 @@ and are not listed here.
## [Unreleased]
## [2.3.0] — 2026-11-21
The last feature release: from here on the project is in **maintenance mode**
([`CONTRIBUTING.md`](CONTRIBUTING.md)).
### Added
- **Content labels, an age check and blurred images.** Posts, chapters and albums — and single
gallery photos — can carry labels from a fixed list (horror, blood, jump scares, violence,
self-harm, death, politics, religion, strong language, flashing lights, spoilers) and an age
rating (13+, 16+, 18+).
- A banner names the labels in the page's language.
- For the visual labels, images are blurred until "Show images" is ticked. That is a real
checkbox, and the blur is plain CSS, so it works from the keyboard and without JavaScript.
- An age-rated text stays folded until the reader confirms their age in a native dialog. It
never pops up on its own, and Esc never means "yes". The answer stays in the browser
(`localStorage`: an age threshold, never a birth date).
- Cards, the photo viewer, RSS descriptions and OG cards carry the warning too. The privacy
policy (§6) lists the new local-storage item
([#138](https://github.com/poli0981/poli0981-dev/pull/138)).
- **The admin publishes on its own.** Every save or delete starts the publish workflow; bursts
coalesce. The admin now follows a change until it is actually live: the build records the
content commit it was made from (`version.content` in `/api/health`), and the publish bar
shows building / waiting for review / merged and deploying / live / failed. The editor and
gallery manager set labels, age ratings and per-photo labels
([#137](https://github.com/poli0981/poli0981-dev/pull/137)).
- **Qodana** (JetBrains, Qodana for JS) on every pull request and on `main`, with a zero-problem
quality gate. Results go to Qodana Cloud and, for `main`, to code scanning
([#135](https://github.com/poli0981/poli0981-dev/pull/135)).
- **Licence check over the whole dependency tree**: every package in `package-lock.json`, with
reviews per package instead of per licence. A package with no licence fails CI (#135).
- Maintenance-mode governance:
- `CONTRIBUTING.md`, in Vietnamese and English;
- a language-problem issue form, with blank issues off and questions sent to Discussions;
- a "kind of change" checklist in the pull request template;
- a triage workflow that labels and closes new-feature requests.
### Changed
- Admin commits in the public content repository no longer carry the admin's email address; the
private audit log keeps who did what (#137).
- The admin's checks now match the content schema, so a save cannot queue a failing build:
chapters are positive whole numbers, `cover` and `coverMedia` exclude each other, and an album
must be a slug that already has photos (#137).
- Deleting an image is refused while the **live** site's content still uses it, not only while
`main` does (#137).
- The post page uses the cover's alt text when one is set (#138); the editor has a field for it,
and the media picker takes alt text for uploads (#137).
- One-shot stories (`stories/<slug>.md`) can be created and edited in the admin (#137).
- Dependencies, keeping the three-day cooldown: astro 7.4.12, @astrojs/cloudflare 14.4.8,
@astrojs/svelte 9.1.6, jose 6.2.17, marked 18.2.1, wrangler 4.164.0, eslint 10.15.0,
typescript-eslint 8.73.0, prettier 3.10.1, prettier-plugin-svelte 4.2.0 (14 Svelte files
reformatted; the rendered markup is unchanged), playwright 1.65.1, knip 6.45.1
([#134](https://github.com/poli0981/poli0981-dev/pull/134),
[#136](https://github.com/poli0981/poli0981-dev/pull/136)). The SonarQube scan action is at 8.5.0
and the OSV-Scanner workflow at 2.7.1 ([#127](https://github.com/poli0981/poli0981-dev/pull/127),
[#128](https://github.com/poli0981/poli0981-dev/pull/128)).
### Fixed
- In the editor, Ctrl/⌘+S while typing in a tags field saved the previous tags (#137).
- Qodana's first findings (#135):
- the smoke test's forged Access token is built at run time instead of sitting in the source
as a token literal;
- redundant escapes in a Markdown-to-text regex;
- a single-character alternation in the CSP check;
- a heading table keyed by a mixed-script property name.
### Security
- deepmerge GHSA-gcqx-w48m-w2h4 (alias CVE-2026-93753) was withdrawn on 2026-11-16, and its
Dependabot alert is closed. The OSV-Scanner ignore entries for it are gone (#134).
- Node.js 26.13.1 (security release of 2026-11-10) is what CI and the build use (`.nvmrc` = 26).
## [2.2.0] — 2026-11-10
### Added
@@ -218,7 +292,8 @@ The public launch is tagged `v1-launch`; the 1.x changes after it were not tagge
- **2026-10** — Custom Worker entry in front of every page; Workers Rate Limiting; Web Analytics;
topic email aliases; R2 media; the Turnstile gate; the admin at `admin.poli0981.dev`.
[Unreleased]: https://github.com/poli0981/poli0981-dev/compare/v2.2.0...HEAD
[Unreleased]: https://github.com/poli0981/poli0981-dev/compare/v2.3.0...HEAD
[2.3.0]: https://github.com/poli0981/poli0981-dev/compare/v2.2.0...v2.3.0
[2.2.0]: https://github.com/poli0981/poli0981-dev/compare/v2.1.2...v2.2.0
[2.1.2]: https://github.com/poli0981/poli0981-dev/compare/v2.1.1...v2.1.2
[2.1.1]: https://github.com/poli0981/poli0981-dev/compare/v2.1.0...v2.1.1
+84
View File
@@ -0,0 +1,84 @@
# Contributing
> **Tiếng Việt ở bên dưới.** / Vietnamese below.
## Maintenance mode
Since **v2.3.0 (November 2026)** this project is in **maintenance mode**. The site is complete; it
is kept healthy, but **no new features are being added**. Only these changes are accepted:
1. **Dependency updates** on the regular schedule (Dependabot weekly, a combined update about
once a month, always after a 3-day cooldown).
2. **Security**: a dependency advisory of **High or Critical** severity, or a serious
vulnerability in the runtime itself (Node.js, the Workers runtime), fixed as soon as
possible — together with a feature only when the owner judges it truly necessary.
3. **Major language, runtime or framework upgrades**: Node.js 26 → 28, TypeScript 7.1 replacing
the TypeScript 6 API alias, the next Astro or Svelte major, and the like.
4. **Bugs**: anything that does not work as intended, including **UI/UX** glitches and
**accessibility** barriers ([ACCESSIBILITY.md](ACCESSIBILITY.md)).
5. **Language**: spelling mistakes that could mislead, and wording that does not fit the culture
or the local voice, in Vietnamese or English.
**Not accepted: new features.** An issue or pull request asking for one is labelled
`enhancement` + `out-of-scope` and closed automatically
([`.github/workflows/triage.yml`](.github/workflows/triage.yml)). If it was closed by mistake,
reply on it and the owner will take another look; an exception the owner accepts carries the
`maintenance-exception` label. Ideas are still welcome in
[Discussions](https://github.com/poli0981/poli0981-dev/discussions), without any promise.
### How to report
- **A problem on the website**: the "Báo lỗi / Report a problem" button on the page itself, or the
bug report form under [Issues](https://github.com/poli0981/poli0981-dev/issues/new/choose).
- **An accessibility barrier**: the accessibility form under Issues.
- **A spelling or wording problem**: the language form under Issues.
- **A security vulnerability**: privately — see [SECURITY.md](SECURITY.md). Never in a public
issue.
### Pull requests
Welcome for the five kinds of change above. Keep one change per pull request, follow the checks
in the [pull request template](.github/pull_request_template.md), and run the commands listed in
[README.md](README.md#commands) before opening it. CI must be green — `build` is required, and
the SonarCloud and Qodana gates have to pass too. Commits on `main` are signed.
---
## Chế độ bảo trì
Từ **v2.3.0 (tháng 11/2026)**, dự án ở **chế độ bảo trì**. Trang web đã hoàn chỉnh; repo vẫn được giữ
cho khoẻ mạnh nhưng **không thêm tính năng mới**. Chỉ nhận những thay đổi sau:
1. **Cập nhật dependency** định kỳ (Dependabot hằng tuần, gộp một lần khoảng mỗi tháng, luôn sau
3 ngày "nguội").
2. **Bảo mật**: lỗ hổng trong dependency ở mức **High hoặc Critical**, hoặc lỗ hổng nghiêm trọng của
chính runtime (Node.js, Workers runtime) — sửa sớm nhất có thể; kèm tính năng chỉ khi chủ repo
đánh giá là thật sự cần thiết.
3. **Nâng cấp lớn ngôn ngữ, runtime, framework**: Node.js 26 → 28, TypeScript 7.1 thay alias API
TypeScript 6, bản major tiếp theo của Astro hay Svelte…
4. **Lỗi**: mọi thứ không chạy đúng ý định, gồm cả lỗi **UI/UX** và rào cản **accessibility**
([ACCESSIBILITY.md](ACCESSIBILITY.md)).
5. **Ngôn ngữ**: lỗi chính tả có thể gây hiểu nhầm, câu chữ không hợp văn hoá hay giọng địa phương,
ở cả tiếng Việt lẫn tiếng Anh.
**Không nhận: tính năng mới.** Issue hoặc pull request đề xuất tính năng sẽ được gắn nhãn
`enhancement` + `out-of-scope` và tự động đóng
([`.github/workflows/triage.yml`](.github/workflows/triage.yml)). Nếu bị đóng nhầm, hãy trả lời ngay
trong đó — chủ repo sẽ xem lại; ngoại lệ được chấp nhận mang nhãn `maintenance-exception`. Ý tưởng
vẫn có thể trao đổi trong [Discussions](https://github.com/poli0981/poli0981-dev/discussions), không
cam kết sẽ làm.
### Báo lỗi ở đâu
- **Lỗi trên trang web**: nút "Báo lỗi" ngay trên trang, hoặc form báo lỗi trong
[Issues](https://github.com/poli0981/poli0981-dev/issues/new/choose).
- **Rào cản accessibility**: form accessibility trong Issues.
- **Lỗi chính tả, câu chữ**: form ngôn ngữ trong Issues.
- **Lỗ hổng bảo mật**: báo riêng — xem [SECURITY.md](SECURITY.md). Không mở issue công khai.
### Pull request
Hoan nghênh cho năm loại thay đổi ở trên. Mỗi pull request một thay đổi, làm theo các mục kiểm tra
trong [mẫu pull request](.github/pull_request_template.md), chạy các lệnh trong
[README.md](README.md#commands) trước khi mở. CI phải xanh — `build` là bắt buộc, cổng SonarCloud
và Qodana cũng phải qua. Commit trên `main` có chữ ký.
+17 -3
View File
@@ -4,6 +4,7 @@
[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=poli0981_poli0981-dev&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=poli0981_poli0981-dev)
[![Qodana](https://github.com/poli0981/poli0981-dev/actions/workflows/qodana.yml/badge.svg)](https://github.com/poli0981/poli0981-dev/actions/workflows/qodana.yml)
[![License: GPL-3.0](https://img.shields.io/badge/code-GPL--3.0-blue)](LICENSE)
[![Status: maintenance mode](https://img.shields.io/badge/status-maintenance%20mode-orange)](CONTRIBUTING.md#maintenance-mode)
The personal site of Kokone (SkullMute) — dev portfolio, blog, short fiction and a hub for
the SkullMute channel, in Vietnamese and English. Live at **[poli0981.dev](https://poli0981.dev)**.
@@ -11,6 +12,17 @@ the SkullMute channel, in Vietnamese and English. Live at **[poli0981.dev](https
> Trang cá nhân của Kokone (SkullMute): dự án, blog, truyện ngắn và kênh SkullMute — song ngữ
> Việt/Anh. Tài liệu thiết kế đầy đủ (tiếng Việt) nằm trong [`poli0981.dev-docs/`](poli0981.dev-docs/00_INDEX.md).
## Status
**Maintenance mode since v2.3.0 (November 2026).** The site is complete. It still gets
dependency updates, security fixes (High/Critical advisories, runtime vulnerabilities), major
runtime and framework upgrades, bug fixes (UI/UX and accessibility included) and language fixes,
but no new features. Issues and pull requests asking for one are closed automatically. Details:
[`CONTRIBUTING.md`](CONTRIBUTING.md).
> **Trạng thái:** chế độ bảo trì từ v2.3.0 — chỉ cập nhật dependency, vá bảo mật, nâng cấp
> runtime/framework, sửa lỗi (cả UI/UX, accessibility) và sửa lỗi ngôn ngữ; không thêm tính năng mới.
## Stack
| Layer | Choice |
@@ -84,9 +96,11 @@ pipeline: [`08_CI_CD.md`](poli0981.dev-docs/08_CI_CD.md); changes per release: [
## Admin
`admin.poli0981.dev` is the owner's editor: write and edit posts (commits to the content repo),
upload images (transformed once into AVIF/WebP and stored in R2), manage gallery albums,
publish (opens a submodule-bump PR that CI must pass), review an audit log and manage the IP
denylist. It sits behind Cloudflare Access, and the Worker independently verifies the Access
upload images (transformed once into AVIF/WebP and stored in R2), manage gallery albums, set
content labels and age ratings, review an audit log and manage the IP denylist. Every save or
delete publishes itself: it starts a submodule-bump PR that CI must pass, which then merges and
deploys, and the admin follows it until the change is live (`/api/health` reports the content
commit too). It sits behind Cloudflare Access, and the Worker independently verifies the Access
JWT (≤ 24 hours old) and an email allowlist on every request.
## Security
+8 -1
View File
@@ -36,13 +36,20 @@ Only the currently deployed site (`main` → Cloudflare Workers) is supported. R
tagged (`v2.0.0` onwards, see [`CHANGELOG.md`](CHANGELOG.md)) for reference only — there are
no backports. `https://poli0981.dev/api/health` reports the version and commit that is live.
The project is in maintenance mode ([`CONTRIBUTING.md`](CONTRIBUTING.md)), and security work
is the first thing it keeps doing: a dependency advisory of High or Critical severity, or a
serious vulnerability in Node.js or the Workers runtime, is fixed and deployed as soon as
possible, outside the regular update schedule.
## What the site actually handles
Useful context when judging impact — the site is static and stores almost nothing:
- No visitor accounts or logins, no ad or analytics trackers. The only cookie is
`__Host-gate`, a signed 48-hour pass set after the Turnstile bot check (expiry, random
value and HMAC — no identifier; see `src/lib/gate/`).
value and HMAC — no identifier; see `src/lib/gate/`). Preferences, and the answer to the age
check on age-rated pages (an age threshold, never a birth date), stay in the browser's
`localStorage` and are never sent to the site.
- User-submitted input: the bug-report form (Turnstile-gated, schema-validated, size-capped,
forwarded to an issue in a **private** repository and a Discord webhook) and the bot-check
token exchange at `/api/gate`. Both are rate-limited per client.
+4
View File
@@ -55,6 +55,10 @@
| 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
+3 -3
View File
@@ -69,9 +69,9 @@ poli0981-dev/
│ └── styles/ # global.css (token), prose.css, admin.css
├── tests/ # node:test + support/ (stub astro:*, fake KV/R2/GitHub…) · a11y/ (*.spec.ts: axe-core + bàn phím qua Playwright)
├── workers/widgets/ # worker cron riêng (wrangler.jsonc riêng)
├── .github/ # ci.yml, content-bump.yml, lighthouse.yml, osv-scanner.yml, dependabot.yml, ISSUE_TEMPLATE/ (bug_report, accessibility), pull_request_template.md
├── astro.config.mjs · wrangler.jsonc · sonar-project.properties · lefthook.yml · knip.json
└── LICENSE (GPL-3.0) · CONTENT-LICENSE.md · DISCLAIMER.md · THIRD-PARTY-NOTICES.md · SECURITY.md · ACCESSIBILITY.md · CHANGELOG.md
├── .github/ # ci.yml, content-bump.yml, lighthouse.yml, osv-scanner.yml, qodana.yml, triage.yml, dependabot.yml, ISSUE_TEMPLATE/ (config, bug_report, accessibility, language), pull_request_template.md
├── astro.config.mjs · wrangler.jsonc · sonar-project.properties · qodana.yaml · lefthook.yml · knip.json
└── LICENSE (GPL-3.0) · CONTENT-LICENSE.md · DISCLAIMER.md · THIRD-PARTY-NOTICES.md · SECURITY.md · ACCESSIBILITY.md · CONTRIBUTING.md · CHANGELOG.md
```
## 4. Rendering & routing
+2
View File
@@ -53,6 +53,8 @@ Alt text ảnh gallery: file `src/assets/gallery/<album>/captions.json` (`{"IMG_
tên vi/en ở `src/i18n` nhóm `labels`): `horror`, `blood`, `jumpscare`, `violence`, `self-harm`,
`death` — **làm mờ ảnh** + banner; `politics`, `religion`, `strong-language`, `flashing-lights`,
`spoilers` — chỉ banner. Nhãn lạ ⇒ build fail.
- **Album**: nhãn và `ageRating` lấy từ **cả hai** file ngôn ngữ (cùng ảnh, hai trang) — gắn ở một
bản là đủ; mốc tuổi chặt hơn được dùng (`albumWarning()` trong `src/lib/collections.ts`).
- **Từng ảnh** có thể có nhãn riêng: `contentWarning` cạnh caption trong `gallery-photos/<album>.json`
(admin → Gallery → "Nhãn") hoặc `captions.json` (`{"IMG_001.avif": {"vi":"…","en":"…","contentWarning":["blood"]}}`).
- **Giới hạn tuổi** (`ageRating`: `13+` | `16+` | `18+`): phần nội dung thu gọn tới khi người đọc xác
+1 -1
View File
@@ -86,7 +86,7 @@ Rule ghi đè header cho **mọi** request (client không giả được). Worke
| Build variables | `NODE_VERSION=26`, `PUBLIC_TURNSTILE_SITE_KEY=<site key>` |
| Build cache | bật |
Bẫy đã gặp (19/10/2026): Deploy command của nhánh PR từng là `wrangler deploy` ⇒ mỗi PR (cả Dependabot) được đưa lên production 100%. Ngược lại, nếu Deploy command của `main` là `versions upload` thì merge **không** deploy — khi đó promote tay: `npx wrangler versions list` → `npx wrangler versions deploy <id>@100% --yes --message "main <sha>"`. Xác minh sau mỗi merge: `curl https://poli0981.dev/api/health` phải trả đúng `version.commit`.
Bẫy đã gặp (19/10/2026): Deploy command của nhánh PR từng là `wrangler deploy` ⇒ mỗi PR (cả Dependabot) được đưa lên production 100%. Ngược lại, nếu Deploy command của `main` là `versions upload` thì merge **không** deploy — khi đó promote tay: `npx wrangler versions list` → `npx wrangler versions deploy <id>@100% --yes --message "main <sha>"`. Xác minh sau mỗi merge: `curl https://poli0981.dev/api/health` phải trả đúng `version.commit` (và `version.content` = commit repo nội dung đã publish). Từ v2.3.0 admin tự xuất bản sau mỗi lần lưu ⇒ Deploy command của `main` **phải** là `npx wrangler deploy`, nếu không mọi lần lưu dừng ở pha "đã merge — đang deploy" (đã xảy ra từ 10/2026 tới 11/2026: mọi deploy trong thời gian đó là promote tay).
- Local (khẩn cấp): `npm run build && npx wrangler deploy` (lần đầu wrangler mở OAuth login).
- Gắn domain: Workers & Pages → worker `poli0981-dev` → Settings → **Domains & Routes → Add → Custom domain** → `poli0981.dev` (tự tạo DNS + cert). `www.poli0981.dev` là custom domain thứ hai; worker entry redirect 301 về apex.
- Worker widgets (không nối Workers Builds): `npx wrangler deploy --config workers/widgets/wrangler.jsonc` → kiểm tra Triggers có cron.
+7 -3
View File
@@ -7,7 +7,10 @@
`npm ci --ignore-scripts` → `check-install-scripts` → `wrangler types` (site + widgets) → prettier → eslint → `astro check` (TS 6) → **`typecheck` bằng TypeScript 7** (in `tsc -v`, kiểm site + widgets) → knip → **`test:coverage`** (`node:test`, ngưỡng 80% dòng, xuất `coverage/lcov.info`) → `npm audit --omit=dev --audit-level=high` → `gen-notices --check` → `check-exif --changed` → build (+ OG, Pagefind, `check-csp-hashes`) → **smoke test** (`npm run smoke`: chạy worker đã build bằng `wrangler dev`, kiểm trang/304/HEAD/`/media`/`/ext-img`/admin 403/`frame-ancestors`, pha ép bật cổng Turnstile kể cả cookie sai định dạng, pha denylist) → **cổng trợ năng** (từ v2.2.0: `npm run preview` chạy nền rồi `npm run test:a11y` — Playwright lái Chrome có sẵn trên runner, không tải trình duyệt; axe-core quét mọi trang trong sitemap của bản build, một trang mỗi template ở theme sáng và bề rộng điện thoại, và menu/tìm kiếm/lightbox/hộp báo lỗi/bảng Aa/bảng pháp lý khi đang mở; sau đó là test bàn phím, reflow 320/360/390px và `forced-colors`) → upload coverage làm artifact. Check `build` là **bắt buộc** (ruleset `main`), nên PR có vi phạm axe không merge được.
- Job **`sonarcloud`** (sau `build`; chạy cho push `main` và PR cùng repo, bỏ qua Dependabot): tải coverage → `SonarSource/sonarqube-scan-action` (pin SHA) với `sonar-project.properties`; trên PR chờ **quality gate** ("Sonar way" cho new code: coverage ≥ 80%, trùng lặp ≤ 3%, rating A, hotspot đã review). Automatic analysis trên SonarCloud **tắt** (CI analysis thay thế); `SONAR_TOKEN` là secret của repo. `.svelte`/`.astro` không được Sonar phân tích — logic quan trọng nằm trong `.ts` để đo được.
- **CodeQL** (default setup, repo public) · **Snyk** (GitHub app) · **`osv-scanner.yml`** (reusable workflow v2.7.0, SARIF, hằng tuần + khi đổi lockfile) · **`lighthouse.yml`** (`treosh/lighthouse-ci-action` pin SHA, preset mobile, chỉ cảnh báo).
- **`content-bump.yml`** (nút **Xuất bản** của admin): trỏ submodule `src/content` về `content/main`, commit lên nhánh `content/bump`, mở/cập nhật PR, auto-merge (squash) nếu diff chỉ `.md/.json`, rồi `gh workflow run ci.yml --ref content/bump` để có check `build` (PR mở bằng GITHUB_TOKEN không kích hoạt `pull_request`). Merge ⇒ Workers Builds deploy.
- **`content-bump.yml`** (từ v2.3.0 admin tự gọi sau **mỗi lần lưu/xoá**; nút **Xuất bản** còn lại để chạy lại; `concurrency` gộp các lần gọi dồn dập): trỏ submodule `src/content` về `content/main`, commit lên nhánh `content/bump`, mở/cập nhật PR, auto-merge (squash) nếu diff chỉ `.md/.json`, rồi `gh workflow run ci.yml --ref content/bump` để có check `build` (PR mở bằng GITHUB_TOKEN không kích hoạt `pull_request`). Merge ⇒ Workers Builds deploy.
- **`qodana.yml`** (từ v2.3.0, PR + push `main` + tay): Qodana for JS (gói Ultimate, token `QODANA_TOKEN`), native mode trên Node 26 của runner sau `npm ci` + sinh types, profile `qodana.recommended` quét cả repo, `failThreshold: 0` (`qodana.yaml` ghi các inspection tắt kèm lý do); kết quả lên Qodana Cloud và — với `main` — SARIF vào Code scanning. Bỏ qua PR Dependabot/fork (không có secret) nên chỉ là check tư vấn. Không phân tích `.astro`/`.svelte`.
- **Kiểm license**: `gen-notices --check` (dependency trực tiếp, bảng trong `THIRD-PARTY-NOTICES.md`) + `check-licenses` (toàn bộ lockfile, ngoại lệ theo gói) trong job `build` — chính sách ở `scripts/license-policy.mjs` (`12_LEGAL/THIRD_PARTY_NOTICES.md`). Qodana license audit cần Ultimate Plus nên không dùng.
- **`triage.yml`** (issues + `pull_request_target`; **không checkout gì** — đọc `scripts/triage.mjs` của nhánh mặc định qua API rồi import từ bộ nhớ, nên không bao giờ chạy code của PR; Sonar S7631 bắt mọi checkout trong `pull_request_target`): đề xuất tính năng ⇒ nhãn `enhancement` + `out-of-scope`, bình luận song ngữ, đóng. Chạy khô bằng `workflow_dispatch`.
- **Bẫy đã gặp**: khi `main` dính advisory, *mọi* PR (cả Dependabot) đỏ vì bước audit ⇒ vá gộp trong một PR rồi đóng các PR Dependabot bị thay thế. `gen-notices --check` từng đếm số gói transitive ⇒ PR bump nào cũng đỏ; nay chỉ kiểm chính sách license.
## 1. Nguyên tắc
@@ -116,8 +119,9 @@ Commit và tag đều ký GPG; không dùng `--no-verify`.
## 8. Branch & release
- `main` protected (ruleset): PR + check `build` xanh; merge kiểu **squash**. Conventional Commits.
- Mỗi PR: CI `build` + SonarCloud quality gate + CodeQL xanh trước khi merge; Workers Builds trên nhánh PR chỉ `versions upload`.
- `main` protected (ruleset): PR + check bắt buộc duy nhất là `build` (ruleset cho phép cả 3 kiểu merge; quy ước của repo là **squash**). Conventional Commits.
- Mỗi PR: ngoài `build` còn phải xanh (theo quy ước, ruleset không ép) SonarCloud quality gate, Qodana (ngưỡng 0) và CodeQL; Workers Builds trên nhánh PR chỉ `versions upload`.
- Chế độ bảo trì (D21): PR tính năng mới bị bot `triage.yml` đóng; mẫu PR có ô chọn 5 loại thay đổi được nhận (`CONTRIBUTING.md`).
- **Release**: tag `vX.Y.Z` có ký GPG trên commit `main` đã deploy + GitHub Release (notes lấy từ `CHANGELOG.md`). Deploy vẫn là "merge `main`" — tag chỉ đánh dấu mốc. `v2.0.0` = đợt nâng cấp 10/2026. Mỗi tag: sửa `sonar.projectVersion` trong `sonar-project.properties` cho khớp.
- Sau merge: kiểm `https://poli0981.dev/api/health` trả đúng commit (`07` §9); nếu Workers Builds không deploy thì promote version của `main` bằng `wrangler versions deploy`.
@@ -1,6 +1,6 @@
# Third-Party Notices / Ghi nhận bên thứ ba
> **Ghi chú nội bộ:** file này gồm 2 phần — (A) phần khung render lên `/legal/third-party`, (B) bảng package **tự sinh** bằng `scripts/gen-notices.mjs` trong CI (dựa trên `license-checker`), CI fail nếu bảng lệch với lockfile. Đừng sửa tay phần B.
> **Ghi chú nội bộ:** file này gồm 2 phần — (A) phần khung render lên `/legal/third-party`, (B) bảng package **tự sinh** bằng `scripts/gen-notices.mjs` trong CI (đọc `package.json` của từng gói đã cài — không dùng `license-checker`), CI fail nếu bảng lệch với lockfile. Đừng sửa tay phần B.
---
@@ -21,7 +21,6 @@ Trang web này được xây dựng bằng phần mềm mã nguồn mở. Mỗi
| Astro + @astrojs/* | MIT | framework |
| Svelte | MIT | islands |
| Tailwind CSS | MIT | styling |
| GSAP | GSAP Standard License (miễn phí, Webflow) | kiểm tra đúng tên license trong bản phát hành khi cài |
| Pagefind | MIT | search |
| @vite-pwa/astro / Workbox | MIT | offline |
| Zod | MIT | validation |
@@ -37,8 +36,9 @@ Trang web này được xây dựng bằng phần mềm mã nguồn mở. Mỗi
## Quy trình sinh tự động
```bash
node scripts/gen-notices.mjs # ghi đè phần (B) từ npm ls --json + license-checker
node scripts/gen-notices.mjs # ghi đè phần (B): dependency trực tiếp, license đọc từ node_modules/<pkg>/package.json
node scripts/gen-notices.mjs --check # CI: so khớp, lệch ⇒ exit 1
node scripts/check-licenses.mjs # CI: toàn bộ package-lock.json (transitive + binary mọi nền tảng)
```
Quy tắc: package mới có license ngoài allowlist (MIT, Apache-2.0, ISC, BSD-2/3, OFL, GSAP Standard) ⇒ script cảnh báo đỏ, phải review tay trước khi merge.
Quy tắc (`scripts/license-policy.mjs`, dùng chung cho hai script): license ngoài allowlist (MIT, Apache-2.0, ISC, BSD-2/3, OFL-1.1, 0BSD, Unlicense, CC0-1.0, BlueOak-1.0.0, Python-2.0; biểu thức SPDX `OR`/`AND`/`WITH` được hiểu) ⇒ CI đỏ, phải review tay và ghi ngoại lệ **theo gói** kèm lý do (hiện có: MPL-2.0 của satori/resvg/lightningcss/axe-core, LGPL-3.0-or-later của libvips trong sharp — đều chỉ chạy lúc build/test). Gói không khai license cũng làm CI đỏ.
+10 -2
View File
@@ -2,7 +2,7 @@
Ước lượng theo "buổi tối" (~2–3h). Nguyên tắc quen thuộc: **xong P0 spikes mới viết feature** — spike nào fail thì sửa kế hoạch khi chưa tốn công.
Trạng thái tại 2026-10-24 (v2.0.0): ✅ xong · 🟡 đang làm · ⬜ chưa.
Trạng thái tại 2026-11-21 (v2.3.0 — **chế độ bảo trì**): ✅ xong · 🟡 đang làm · ⬜ chưa.
## P0 — Spikes ✅
@@ -49,7 +49,15 @@ Trạng thái tại 2026-10-24 (v2.0.0): ✅ xong · 🟡 đang làm · ⬜ chư
- [ ] Test 2 thiết bị thật + 1 máy lạ (bạn bè) — thu 1 vòng feedback
- [ ] Đăng giới thiệu lên các kênh (dùng notify.py 😄), thêm link site vào bio YouTube/GitHub/Discord
## Hướng đi tiếp (sau v2.0)
- **v2.3.0** (11/2026, bản tính năng cuối): nhãn nội dung + hỏi tuổi + ảnh mờ + banner cảnh báo (D22) · admin tự xuất bản và biết khi nào "đã lên web" (D23) · Qodana + kiểm license toàn cây (D24) · **chuyển sang chế độ bảo trì** (D21).
## Chế độ bảo trì (từ v2.3.0, 11/2026)
Không thêm tính năng mới. Chỉ: cập nhật dependency định kỳ · vá bảo mật (advisory High/Critical, lỗ hổng runtime) · nâng cấp lớn ngôn ngữ/runtime/framework · sửa lỗi (cả UI/UX, accessibility) · sửa lỗi ngôn ngữ. Chính sách: `CONTRIBUTING.md`; lịch: `17` §0–§1; bot đóng đề xuất tính năng: `.github/workflows/triage.yml`.
P4 còn mở vẫn làm được vì không phải tính năng. Bảng dưới đây **đóng băng** — giữ để biết đã cân nhắc gì; mục nào chỉ quay lại khi rơi vào một trong năm loại thay đổi được nhận (VD gộp TypeScript 7.1 = nâng cấp lớn).
## Hướng đi đã cân nhắc (đóng băng)
| Hướng | Vì sao | Điều kiện |
|---|---|---|
+15 -3
View File
@@ -2,6 +2,18 @@
Mục tiêu: site "để yên vẫn sống". Tổng thời gian bảo trì định kỳ ~15–30 phút/tuần.
## 0. Chế độ bảo trì (từ v2.3.0, 11/2026 — quyết định D21)
Không thêm tính năng mới. Repo chỉ nhận (`CONTRIBUTING.md`):
1. Cập nhật dependency định kỳ (Dependabot hằng tuần + gộp `npm update --save --before=<hôm nay − 3 ngày>` khoảng mỗi tháng, như PR #123/#134).
2. Bảo mật: advisory **High/Critical** trong dependency hoặc lỗ hổng nghiêm trọng của Node.js/Workers runtime ⇒ sửa và deploy ngay, ngoài lịch; tính năng chỉ khi thật sự cần.
3. Nâng cấp lớn ngôn ngữ/runtime/framework (Node 26 → 28, TS 7.1 thay alias TS 6, Astro/Svelte major…).
4. Sửa lỗi, gồm UI/UX và accessibility.
5. Sửa lỗi ngôn ngữ (chính tả gây hiểu nhầm, câu chữ không hợp văn hoá/giọng địa phương).
Issue/PR đề xuất tính năng: `.github/workflows/triage.yml` (logic `scripts/triage.mjs`) gắn `enhancement` + `out-of-scope`, trả lời song ngữ và đóng. Bỏ qua: chủ repo, bot, mục có nhãn `maintenance-exception` (ngoại lệ do chủ repo quyết), và mọi thao tác do chính chủ repo làm (mở lại, gắn nhãn). Thử khô: Actions → Triage → Run workflow (nhập tiêu đề). Form issue: lỗi, accessibility, ngôn ngữ; blank issue tắt; câu hỏi/ý tưởng → Discussions.
## 1. Lịch định kỳ
| Nhịp | Việc |
@@ -9,7 +21,7 @@ Mục tiêu: site "để yên vẫn sống". Tổng thời gian bảo trì đị
| **Hằng tuần** (thứ 2, sau khi Dependabot chạy) | Triage PR Dependabot: patch/minor xanh CI → merge; security alert → xử lý ≤ 48h. Liếc Discord `#site-reports` |
| **Hằng tháng** | `npm outdated` đọc report weekly; nâng minor còn sót; **nâng tay `@typescript/native`** (Dependabot bỏ qua alias `npm:`) và xem TS 7.1 đã có JS API chưa (`02` §8); xem Web Analytics + Core Web Vitals; liếc Workers Logs (lọc `level: error`) + dashboard admin (trạng thái cron widgets, secret thiếu); SonarCloud không có issue mới trên `main` |
| **Hằng quý** | Nâng major có kế hoạch (Astro/Tailwind/Wrangler — đọc upgrade guide trước); chạy lại ma trận error test `09` §5; backup ngoài (§4) |
| **Hằng năm** | **Xoay secrets**: GITHUB_ISSUES_TOKEN (repo `site-reports`), GITHUB_CONTENT_TOKEN + GITHUB_PUBLISH_TOKEN (admin), GATE_SECRET (vô hiệu mọi vé cổng — làm lúc ít khách), STEAM_API_KEY, SONAR_TOKEN · rà `ADMIN_EMAILS` + policy Access · cập nhật `Expires` trong security.txt · đọc lại 7 trang legal (đổi thì tăng `v` của legalAck) · **rà trợ năng**: đọc lại `/legal/accessibility` + `ACCESSIBILITY.md`, đi một lượt bằng bàn phím và trình đọc màn hình, cập nhật ngày rà ở cả hai nơi · kiểm tra thẻ thanh toán còn hạn cho auto-renew domain |
| **Hằng năm** | **Xoay secrets**: GITHUB_ISSUES_TOKEN (repo `site-reports`), GITHUB_CONTENT_TOKEN + GITHUB_PUBLISH_TOKEN (admin), GATE_SECRET (vô hiệu mọi vé cổng — làm lúc ít khách), STEAM_API_KEY, SONAR_TOKEN, QODANA_TOKEN (token project trên Qodana Cloud → secret repo) · rà `ADMIN_EMAILS` + policy Access · cập nhật `Expires` trong security.txt · đọc lại 7 trang legal (đổi thì tăng `v` của legalAck) · **rà trợ năng**: đọc lại `/legal/accessibility` + `ACCESSIBILITY.md`, đi một lượt bằng bàn phím và trình đọc màn hình, cập nhật ngày rà ở cả hai nơi · kiểm tra thẻ thanh toán còn hạn cho auto-renew domain |
Đặt reminder: dùng chính hệ notify/cron GitHub Actions quen thuộc — workflow cron tháng/quý/năm bắn Discord nhắc việc (input sẵn trong repo `.github`).
@@ -18,7 +30,7 @@ Mục tiêu: site "để yên vẫn sống". Tổng thời gian bảo trì đị
1. Branch `chore/upgrade-<pkg>-vX` → đọc CHANGELOG/upgrade guide chính thức.
2. `npm i <pkg>@latest` → chạy full CI local (`format/lint/check/knip/build`).
3. Mở PR → CI (`build` + smoke) + SonarCloud xanh; Workers Builds upload version preview của nhánh → bấm qua 6 trang đại diện + search + form report (dashboard → Versions → alias của nhánh).
4. Squash-merge → kiểm `/api/health` trả đúng commit (Workers Builds không deploy ⇒ `wrangler versions deploy`) → chạy nhanh ma trận lỗi 3 dòng đầu (404/403/429).
4. Squash-merge → Workers Builds deploy `main` (Deploy command `npx wrangler deploy`, `07` §9) → kiểm `/api/health` trả đúng commit (nếu vẫn bản cũ: Deploy command lại thành `versions upload` ⇒ sửa trong dashboard, tạm thời `wrangler versions deploy <id>@100%`) → chạy nhanh ma trận lỗi 3 dòng đầu (404/403/429).
5. Ghi vào `CHANGELOG.md`; ghi 1 dòng vào `poli0981.dev-docs/00_INDEX.md` nếu có breaking change ảnh hưởng quyết định cũ.
**Rollback**: `npx wrangler versions list` → `npx wrangler versions deploy <id-cũ>@100% --yes` (hoặc `wrangler rollback`). Secret mới đặt sau version đó sẽ không có trong version cũ — đặt lại nếu cần.
@@ -27,7 +39,7 @@ Mục tiêu: site "để yên vẫn sống". Tổng thời gian bảo trì đị
- **Uptime** (tuỳ chọn, free): UptimeRobot/StatusCake ping `https://poli0981.dev/` 5 phút/lần → alert email/Discord. Đủ dùng, không cần status page.
- **Lỗi runtime**: Workers Logs (log JSON có `event`/`ray`, `06` §10) → tra theo Ray ID mà người dùng gửi kèm báo lỗi; không cần Sentry ở quy mô này (ADR-05).
- **Đang chạy bản nào**: `curl https://poli0981.dev/api/health` → `version.id` + `version.commit`; dashboard admin hiện cùng thông tin.
- **Đang chạy bản nào**: `curl https://poli0981.dev/api/health` → `version.id` + `version.commit` + `version.content` (commit repo nội dung mà bản build dùng); dashboard admin hiện cùng thông tin, thanh Xuất bản báo pha "đang build / đã merge — đang deploy / đã lên web".
- **Admin**: `/admin/activity/` (audit log 90 ngày + commit repo content) — liếc khi nghi có thao tác lạ.
- **Cron widgets**: tự cảnh báo qua Discord khi fail 3 lần (11 §5).
+76
View File
@@ -0,0 +1,76 @@
/**
* Maintenance-mode triage (CONTRIBUTING.md): an issue or pull request that asks for a new
* feature is labelled and closed with an explanation; everything else is left for the owner.
* .github/workflows/triage.yml reads this file from the default branch through the API and runs
* it in actions/github-script: nothing is checked out, so no pull request's code ever runs.
*
* Deliberately narrow: only clear signals count (the title, or a label the reporter could not
* set by accident). A bug report that happens to say "add" is not a feature request.
*/
export const LABELS = {
/** Marks a feature request (GitHub's default label, reused). */
feature: "enhancement",
/** Closed because new features are out of scope while the project is in maintenance mode. */
closed: "out-of-scope",
/** The owner's exception: the bot leaves the item alone. */
exception: "maintenance-exception",
};
// Tested against the trimmed title. Each pattern is linear: no two quantifiers compete for the
// same characters.
const FEATURE_TITLES = [
/^feat(\([^)]*\))?!?:/i, // conventional commits: "feat: …", "feat(ui)!: …"
/^\[(feat|feature|features|enhancement|request|idea|tính năng|đề xuất)\b/iu,
/\bfeature[\s-]+request\b/i,
/\b(new|add|adding)(\s+a)?\s+feature\b/i,
/(đề xuất|yêu cầu|thêm|bổ sung)\s+tính năng|tính năng mới/iu,
];
/** People whose items are never closed: the owner and collaborators, and bots. */
const TRUSTED = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
/**
* What to do with one issue or pull request.
*
* @param {{ title: string, labels: string[], author: string, association?: string,
* sender?: string, owner?: string, state?: string }} item
* `association` is the author's (GitHub's author_association); `sender` is whoever
* triggered the event, so the owner reopening or relabelling an item is never undone.
* @returns {{ action: "close" | "none", reason: string }}
*/
export function decide(item) {
const labels = item.labels.map((label) => label.toLowerCase());
if (item.state && item.state !== "open") return { action: "none", reason: "not open" };
if (labels.includes(LABELS.exception)) return { action: "none", reason: "owner's exception" };
if (TRUSTED.has(item.association ?? "")) return { action: "none", reason: "trusted author" };
if (item.author.endsWith("[bot]")) return { action: "none", reason: "bot" };
if (item.sender && item.owner && item.sender === item.owner) {
return { action: "none", reason: "the owner acted on it" };
}
if (labels.includes(LABELS.feature)) return { action: "close", reason: "labelled as a feature" };
const title = item.title.trim();
if (FEATURE_TITLES.some((pattern) => pattern.test(title))) {
return { action: "close", reason: "the title asks for a feature" };
}
return { action: "none", reason: "not a feature request" };
}
/** The comment left on a closed item, in both of the project's languages. */
export function closingComment(kind) {
const what = kind === "pull_request" ? "pull request" : "issue";
return [
"**Vietnamese / Tiếng Việt** — Cảm ơn bạn! Dự án đang ở **chế độ bảo trì**: không nhận tính năng",
"mới. Repo chỉ nhận cập nhật dependency, vá bảo mật, nâng cấp runtime/framework, sửa lỗi (kể",
"cả UI/UX và accessibility) và sửa lỗi ngôn ngữ. Vì vậy mục này được đóng tự động. Nếu bạn",
"nghĩ đây là lỗi chứ không phải tính năng mới, hãy trả lời bên dưới — chủ repo sẽ xem lại.",
"",
`**English** — Thank you! This project is in **maintenance mode** and does not take new`,
`features. It accepts dependency updates, security fixes, runtime/framework upgrades, bug fixes`,
`(including UI/UX and accessibility) and language fixes, so this ${what} was closed`,
`automatically. If you think it is a bug rather than a new feature, reply below and the owner`,
`will take another look.`,
"",
"→ [CONTRIBUTING.md](https://github.com/poli0981/poli0981-dev/blob/main/CONTRIBUTING.md)",
].join("\n");
}
+1 -1
View File
@@ -4,7 +4,7 @@ sonar.organization=poli0981
sonar.projectKey=poli0981_poli0981-dev
sonar.projectName=poli0981-dev
# Bumped with each release tag; "previous version" new-code periods start from it.
sonar.projectVersion=2.2.0
sonar.projectVersion=2.3.0
sonar.sourceEncoding=UTF-8
# .github is analyzed too: the workflow rules (pinned actions, no npx/install scripts) are
+73
View File
@@ -0,0 +1,73 @@
// Maintenance-mode triage (scripts/triage.mjs): which issues and pull requests the bot closes
// as feature requests, and which it must leave alone.
import assert from "node:assert/strict";
import { describe, it } from "node:test";
import { closingComment, decide, LABELS } from "../scripts/triage.mjs";
const outsider = { labels: [] as string[], author: "someone", association: "NONE" };
describe("triage", () => {
it("closes clear feature requests, in either language", () => {
for (const title of [
"feat: dark mode for the admin",
"feat(ui)!: new home page",
"[Feature] Comments under posts",
"[đề xuất] thêm trang tìm kiếm nâng cao",
"Feature request: RSS for the gallery",
"Add a feature to export posts",
"Đề xuất tính năng: chế độ đọc to",
"Thêm tính năng bình luận",
"Tính năng mới: newsletter",
]) {
assert.equal(decide({ ...outsider, title }).action, "close", title);
}
assert.equal(
decide({ ...outsider, title: "Comments please", labels: ["Enhancement"] }).action,
"close",
);
});
it("leaves bugs, fixes and questions alone, even when they say 'add'", () => {
for (const title of [
"[web-report] Menu does not close on iPhone",
"[a11y] Focus lost after closing the viewer",
"fix: wrong date on the now page",
"Typo in the privacy policy (vi)",
"Please add alt text to the gallery cover",
"How do I run the site locally?",
"Lỗi chính tả trong trang giới thiệu",
]) {
assert.equal(decide({ ...outsider, title }).action, "none", title);
}
});
it("never closes the owner's items, bots, exceptions, or anything already closed", () => {
const title = "feat: something new";
assert.equal(decide({ ...outsider, title, association: "OWNER" }).reason, "trusted author");
assert.equal(decide({ ...outsider, title, author: "dependabot[bot]" }).reason, "bot");
assert.equal(
decide({ ...outsider, title, labels: ["maintenance-exception"] }).reason,
"owner's exception",
);
assert.equal(
decide({ ...outsider, title, sender: "poli0981", owner: "poli0981" }).reason,
"the owner acted on it",
);
assert.equal(decide({ ...outsider, title, state: "closed" }).reason, "not open");
assert.equal(decide({ ...outsider, title, state: "open" }).action, "close");
});
it("explains itself in Vietnamese and English and links the policy", () => {
const issue = closingComment("issue");
assert.match(issue, /chế độ bảo trì/);
assert.match(issue, /maintenance mode/);
assert.match(issue, /this issue was closed/);
assert.match(closingComment("pull_request"), /this pull request was closed/);
assert.match(issue, /CONTRIBUTING\.md/);
assert.deepEqual(Object.values(LABELS), [
"enhancement",
"out-of-scope",
"maintenance-exception",
]);
});
});