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:
1 parent
484907439a
commit
7bcbcf59dd
20 files changed
+541
-23
No files matched your search
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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`
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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ý.
|
||||
@@ -4,6 +4,7 @@
|
||||
[](https://sonarcloud.io/summary/new_code?id=poli0981_poli0981-dev)
|
||||
[](https://github.com/poli0981/poli0981-dev/actions/workflows/qodana.yml)
|
||||
[](LICENSE)
|
||||
[](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
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,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 đỏ.
|
||||
@@ -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 |
|
||||
|---|---|---|
|
||||
|
||||
@@ -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).
|
||||
|
||||
|
||||
@@ -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");
|
||||
}
|
||||
@@ -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
|
||||
|
||||
@@ -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",
|
||||
]);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user