morningman opened a new pull request, #4160: URL: https://github.com/apache/doris-website/pull/4160
## What this adds `doc-tools/skills/doris-release-docs/` — a skill for auditing and updating the user documentation of a Doris release from the commit diff between two refs (for example `4.1.3..4.1.4-rc04`). It is distilled from the 4.1.4 round (#4123), including every mistake made there and the step that now prevents it. ## Workflow 1. **Ask first** which doc branch gets the Chinese version (dev / 4.x / ...) and where to sync afterwards. 2. **Extract the hard user-facing surface** deterministically: FE/BE/MS configs, session variables, grammar, builtin functions, system tables, SHOW/ADMIN commands, HTTP endpoints, metrics, property analyzers, shipped `conf/` files, dependency versions, build modules. This is the baseline that subagent reports can add to but never override. 3. **Classify every production commit** with parallel subagents (split by touched paths — the `[fix](test)` commit that added a session variable is the reason subject tags are ignored). 4. **Decide per change**: FIX / ADD / NEW / NOTE / SKIP / ASK — feature commits with no obvious home, large new capability areas and "open-source build has no implementation" cases are collected into one question for the user. 5. **Write the Chinese docs** for the chosen branch, run the static validator, open a PR. 6. **After approval, sync** to the other branches and English — with a master-vs-tag difference table first, because the dev docs describe master (four variables, three defaults, the Paimon version and a module rename differed in the 4.1.4 round). ## Iron rules - Anything a user can perceive needs a doc. - Every new feature, behavior change, default change or removal carries a "since version X.Y.Z" note, verified against the release tags, on every release line it shipped on. - Every feature commit needs a documented home, or a question to the user — never a silent "no location found". - Facts come only from the code at the release tag: defaults, mutability, gating conditions, error strings, column names, privilege checks, counting semantics. - Unreleased capabilities are recorded, not documented. - Sidebars are shared across locales, so a new page waits for its English twin; removed features keep their page as a removal notice with a migration mapping; no `yarn build`, static checks only. ## Scripts | Script | Purpose | | --- | --- | | `surface-diff.sh` | per-area diffs between two refs plus an identifier list | | `split-commits.sh` | production vs test-only commits, cut into batches | | `check-version-claims.py` | which tags contain an identifier; `--path` for FE/BE name clashes | | `compare-refs.py` | default value, mutability and presence of configs/variables on two refs (handles both `@VariableMgr.VarAttr` and master's `@VarAttrDef.VarAttr`) | | `validate-docs.py` | front matter, relative links, bare JSX-like tags in `.mdx` (import-aware), CJK in English trees, forbidden identifiers, table column consistency | All five were run against the real 4.1.3..4.1.4-rc04 range and against the merged history of #4123; the validator reports 3 genuine pre-existing issues over 488 files and nothing else. ## References - the two subagent prompts (classification, cross-tree port) - writing conventions: version-note wording per situation, FE/BE config entry formats, the session-variable page format, removal pages, MDX constraints, and a "claim → how to verify it" table - a report template - `pitfalls.md`: the 21 concrete mistakes from the 4.1.4 round 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01GRr7pw6ymrf99x3DUr2zxg -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
