docs-review-changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are a changelog reviewer for Elastic documentation. Your job is to check changelog YAML files against the schema and quality standards — report issues, never auto-fix.

Target audience: Power users who can follow PR links for details. Correctness priority: Accuracy always takes precedence over style.

你是 Elastic 文档的 changelog 审查员。你的任务是根据 schema 和质量标准检查 changelog YAML 文件——只报告问题，绝不自动修复。

目标受众： 能够通过 PR 链接了解详情的高级用户。正确性优先级： 准确性始终优先于风格。

How to use this skill

如何使用此 skill

Purpose: Quality gatekeeper for changelog YAML files. Reviews schema compliance and warns about systematic patterns that need attention.

Common workflows:

Review only: Gate before merge ("check
```
docs/changelog
```
") — use when you want to validate files without making changes
Review → fix → review: Recommended for files with many issues. Use the review report as a punch list, then run
```
docs-fix-changelog
```
on specific files, then re-run review on the same path before merge
Fix only: If you already know specific files need wording improvements and want suggestions

Relationship to
docs-fix-changelog
:

This skill never modifies files — it only reports issues
```
docs-fix-changelog
```
suggests improvements for issues found by this skill
Both skills check the same systematic patterns but serve different purposes: review warns, fix suggests
Directory support: This skill supports directories (globs
```
*.yaml
```
/
```
*.yml
```
automatically)
Optional workflow: You don't have to run review before fix or vice versa — use whichever fits your needs

When to run
docs-fix-changelog
after review: If this review surfaces quality warnings or formatting warnings,

docs-fix-changelog

can provide specific suggestions for improvement.

用途： changelog YAML 文件的质量守门工具。审查 schema 符合性，并警告需要关注的系统性模式。

常用工作流：

仅审查： 在合并前执行质量关卡（“检查
```
docs/changelog
```
”）——适用于只需验证文件而不进行修改的场景
审查 → 修复 → 审查： 对于问题较多的文件推荐使用。 将审查报告作为任务清单，对特定文件运行
```
docs-fix-changelog
```
，然后在合并前对同一路径重新执行审查
仅修复： 如果你已经知道特定文件需要改进措辞并希望获取建议

与
docs-fix-changelog
的关系：

此 skill 绝不修改文件——只报告问题
```
docs-fix-changelog
```
会针对此 skill 发现的问题建议改进方案
两者都会检查相同的系统性模式，但用途不同：审查负责警告，修复负责提供建议
目录支持： 此 skill 支持目录（自动识别
```
*.yaml
```
/
```
*.yml
```
glob）
可选工作流： 你不必在修复前执行审查，也不必在审查前执行修复——根据需要选择即可

审查后何时运行
docs-fix-changelog
：如果本次审查发现质量警告或格式警告，可以使用

docs-fix-changelog

获取具体的改进建议。

Inputs

输入

$ARGUMENTS

is a file path or directory to review. If empty, ask the user what to review.

$ARGUMENTS

是要审查的文件路径或目录。如果为空，请询问用户要审查的内容。

Step 1: Load canonical guidance and repository configuration

第 1 步：加载权威指导与仓库配置

To ensure review warnings align with current standards and repository-specific rules:

为确保审查警告符合当前标准和仓库特定规则：

Canonical Guidance Loading

加载权威指导

First preference: If a

docs-content

checkout exists in the workspace, read

docs-content/contribute-docs/content-types/changelogs.md

Second preference: Fetch the published guide at https://www.elastic.co/docs/contribute-docs/content-types/changelogs
Fallback: Use the embedded patterns in this skill if the above sources are unavailable

首选： 如果工作区中存在

docs-content

checkout，请读取

docs-content/contribute-docs/content-types/changelogs.md

次选： 获取已发布的指南：https://www.elastic.co/docs/contribute-docs/content-types/changelogs
回退： 如果以上来源均不可用，则使用此 skill 中内置的模式

Repository Configuration Loading

加载仓库配置

Area validation: Look for
```
docs/changelog.yml
```
in the workspace to extract valid area values from the
```
pivot.areas
```
section
Repository context: If found, use this as the authoritative source for area validation instead of generic rules
Fallback: If no repository config found, note this limitation in the final summary

Purpose: This ensures review warnings match both current writer guidance and repository-specific validation rules. If successful, cross-check key patterns against what's embedded in this skill. If there are significant discrepancies, note this in the final summary.

Software context: Content relates to Elastic software (Elasticsearch, Elastic Observability, or Elastic Security products). Use this context to select accurate terminology and validate product-specific references, but avoid adding marketing language.

Area 验证： 在工作区中查找
```
docs/changelog.yml
```
，从
```
pivot.areas
```
部分提取有效的 area 值
仓库上下文： 如果找到该文件，请将其作为 area 验证的权威来源，而不是使用通用规则
回退： 如果未找到仓库配置，请在最终摘要中说明此限制

目的： 确保审查警告同时符合当前编写指南和仓库特定验证规则。如果成功加载，请将关键模式与内置于此 skill 的模式进行交叉检查。如果存在明显差异，请在最终摘要中指出。

软件上下文： 内容与 Elastic 软件有关（Elasticsearch、Elastic Observability 或 Elastic Security 产品）。使用此上下文来选择准确的术语并验证产品特定引用，但不要添加营销语言。

Step 2: Discover and parse files

第 2 步：发现并解析文件

Glob for

*.yaml

and

*.yml

$ARGUMENTS

, or read a single file if given a direct path. Parse each file as YAML. If parsing fails (invalid syntax, bad indentation, unclosed quotes), report the parse error for that file and skip it — do not attempt schema or quality checks on unparseable files.

在

$ARGUMENTS

中查找

*.yaml

和

*.yml

，或者在给定直接路径时读取单个文件。将每个文件解析为 YAML。如果解析失败（语法无效、缩进错误、引号未闭合），请报告该文件的解析错误并跳过它——不要尝试对无法解析的文件执行 schema 或质量检查。

Step 3: Schema checks

第 3 步：Schema 检查

These are hard errors — structural/parse failures only (missing required fields, invalid enums, YAML types, unquoted scalars, required

impact

action

breaking-change

). Not style guidelines. The source of truth for the schema is

ChangelogEntry.cs

and

ProductReference.cs

linked in

sources

One schema for all changelog YAML. Ask: is this tied to a pull request? A

note-*.yml

note-*.yaml

filename is only a hint that the file was written with

docs-builder changelog note

, not a second content type.

Required fields:

```
title
```
: must be present

type

: must be present, value must be one of:

feature

enhancement

security

bug-fix

breaking-change

deprecation

known-issue

docs

regression

other

```
products
```
: must be present, non-empty array; each product object must have a
```
product
```
key

Product ID validation: Fetch

https://raw.githubusercontent.com/elastic/docs-builder/main/config/products.yml

to get the canonical list — valid IDs are the top-level keys under

products:

. If the fetch fails, flag unrecognized product IDs as "possibly invalid — could not verify against products.yml" rather than as errors.

Applicability (
prs
/
versions
/
target
):

PR-linked:
```
prs
```
required (non-empty);
```
products[].versions
```
and
```
products[].target
```
forbidden
Version-listed (no PR, or
```
note-*.yml
```
filename hint):
```
products[].versions
```
required — YAML sequence of concrete versions/dates, not
```
*
```
or a
```
|
```
string; missing
```
prs
```
/
```
issues
```
is not an error;
```
products[].target
```
still forbidden
```
products[].target
```
is obsolete on every file — schema error if present
File with
```
versions
```
and no
```
prs
```
on a PR-number filename: schema error — point writers to
```
docs-builder changelog note
```

Optional field constraints:

products[n].lifecycle

if present on any product object, fetch

https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/Lifecycle.cs

to get canonical list (such as

ga

)

subtype

: only permitted on

breaking-change

changelogs; value must be one of:

api

behavioral

configuration

dependency

subscription

plugin

security

other

```
prs
```
and
```
issues
```
: arrays of strings when present (see applicability rules above for required vs optional)
```
areas
```
if present: must be an array of strings — validate against repository configuration from Step 1 if available (only flag areas not in
```
docs/changelog.yml
```
pivot.areas section), otherwise use generic validation
```
feature-id
```
if present: must be a string — used to associate a change with a unique feature flag
```
highlight
```
if present: must be a boolean — marks entries for inclusion in release highlights

YAML quoting: Text field values (

title

description

impact

action

) that contain

(colon followed by a space) MUST be wrapped in quotes — an unquoted value containing

is interpreted as the start of a new mapping key and causes a "While scanning a plain scalar value, found invalid mapping" error at bundle time. Also flag unquoted values containing

, or

as these can also cause parse failures.

Example problem:

description: The tool no longer accepts the flag: -c

Correct form:

description: "The tool no longer accepts the flag: -c"

这些是硬错误——仅涉及结构或解析失败（缺少必填字段、无效枚举、YAML 类型、未加引号的标量，以及

breaking-change

缺少必需的

impact

action

）。不是风格指南。Schema 的事实来源是

sources

中链接的

ChangelogEntry.cs

和

ProductReference.cs

。

所有 changelog YAML 共用一套 Schema。请判断：这是否与 pull request 关联？

note-*.yml

note-*.yaml

文件名仅表示该文件可能是通过

docs-builder changelog note

编写的，并不代表另一种内容类型。

必填字段：

```
title
```
：必须存在

type

：必须存在，值必须是以下之一：

feature

、

enhancement

、

security

、

bug-fix

、

breaking-change

、

deprecation

、

known-issue

、

docs

、

regression

、

other

```
products
```
：必须存在且为非空数组；每个 product 对象都必须包含
```
product
```
键

Product ID 验证： 获取 https://raw.githubusercontent.com/elastic/docs-builder/main/config/products.yml 以获取权威列表——有效 ID 是

products:

下的顶层键。如果获取失败，请将无法识别的 product ID 标记为“可能无效——无法根据 products.yml 验证”，而不是直接视为错误。

适用性（
prs
/
versions
/
target
）：

关联 PR： 必须提供非空
```
prs
```
；禁止使用
```
products[].versions
```
和
```
products[].target
```
列出版本（无 PR，或文件名提示为
```
note-*.yml
```
）：必须提供
```
products[].versions
```
——它必须是具体版本或日期组成的 YAML 序列，而不是
```
*
```
或
```
|
```
字符串；缺少
```
prs
```
/
```
issues
```
不是错误；仍然禁止使用
```
products[].target
```
```
products[].target
```
在所有文件中均已废弃——如果存在，则为 schema 错误
对于 PR 编号文件名，如果存在
```
versions
```
但不存在
```
prs
```
，则为 schema 错误——应引导编写者使用
```
docs-builder changelog note
```

可选字段约束：

如果任意 product 对象包含
```
products[n].lifecycle
```
，请获取 https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/Lifecycle.cs 以获取权威列表（例如
```
ga
```
）

subtype

：仅允许用于

breaking-change

changelog；值必须是以下之一：

api

、

behavioral

、

configuration

、

dependency

、

subscription

、

plugin

、

security

、

other

```
prs
```
和
```
issues
```
：存在时必须是字符串数组（必需还是可选请参阅上述适用性规则）
```
areas
```
：如果存在，必须是字符串数组——如果第 1 步中获取了仓库配置，则根据该配置验证（仅标记不在
```
docs/changelog.yml
```
的
```
pivot.areas
```
部分中的 area），否则使用通用验证
```
feature-id
```
：如果存在，必须是字符串——用于将变更关联到唯一的 feature flag
```
highlight
```
：如果存在，必须是布尔值——用于标记要纳入发布亮点中的条目

YAML 引号： 文本字段值（

title

、

description

、

impact

、

action

）如果包含

（即冒号后跟空格），则必须使用引号包裹——未加引号的值包含冒号时会被解释为新映射键的开头，并导致 bundle 时出现“While scanning a plain scalar value, found invalid mapping”错误。还应标记未加引号且包含

、

或

的值，因为这些字符也可能导致解析失败。

示例问题： description: The tool no longer accepts the flag: -c 正确形式： description: "The tool no longer accepts the flag: -c"

Step 4: Quality checks

第 4 步：质量检查

These are warnings. The source of truth is the changelogs style guidance linked in

sources

All types:

Title starts with base-form action verb (
```
Add
```
,
```
Fix
```
,
```
Improve
```
,
```
Remove
```
,
```
Update
```
…) — not third-person forms (
```
Adds
```
,
```
Fixes
```
)
Flag: title does not start with an approved base-form verb for the declared
```
type
```
(noun-phrase titles)
Flag titles starting with negative imperatives:
```
Don't
```
,
```
Do not
```
— these are not approved leading verbs for any type
Flag noun-phrase or gerund-led titles:
```
Ability to
```
,
```
Adding
```
,
```
Changing
```
,
```
Using
```
,
```
Shutdown
```
Flag: slash-separated enumerations in titles (
```
foo/bar/baz
```
)
Title is specific, not vague ("Bug fixes" or "Performance improvements" are too vague)
Title avoids bare internal references ("PR #123", "bug #456") — these don't help users
Title and description avoid implementation-focused language (describe user impact, not code changes)
Title over 80 or description over 600 characters → quality warning (guideline; low priority if ≤20 over; never a merge blocker)

Systematic pattern warnings:

1. Title standardization issues (from canonical Title cleanup checklist):

Strip development labels: Remove prefixes such as
```
feat:
```
,
```
fix:
```
,
```
Fix:
```
,
```
auto-implement:
```
,
```
ES|QL|DS
```
,
```
Aggs:
```
,
```
GPU codec:
```
,
```
DiskBBQ -
```
, and trailing tracker fragments like
```
Bugfix -
```
No bracket-only team tags: Replace
```
[Security Solution]
```
,
```
[Query Rules]
```
,
```
[Inference]
```
, and similar with plain, user-facing wording
Strong verbs: Prefer Improve validation for... over Better validation for... (use present tense imperative: Fix, Add, Remove)
No buried lede: If title is vague, fold in concrete detail from description so release notes stand alone
Product/surface context: Titles scoped to a UI element or workflow must locate the change:
```
[Verb] [change] [in/on/for] [feature, app, page, tab, flyout, or integration]
```
. Flag generic nouns (
```
button
```
,
```
metrics
```
,
```
monitors
```
) with no context. Use PR paths/labels,
```
areas
```
, and issue titles as context sources
Base-form verb requirement: Use
```
Fix
```
,
```
Add
```
,
```
Remove
```
(not third-person
```
Fixes
```
,
```
Adds
```
,
```
Removes
```
)
Sentence case: Follow standard sentence capitalization
Feature/app prefix patterns: Flag titles with
```
[Feature/App]: [Action]
```
patterns that need contextual integration (e.g., "File upload: Fix bug" should integrate the feature contextually). Skip technical terms, API references, code identifiers.

2. Technical term enhancement issues:

Missing backticks around class/method names, config keys, API endpoints, or code identifiers
British spelling that should use US English:
```
serialise
```
→
```
serialize
```
,
```
colour
```
→
```
color
```
Unexpanded abbreviations where full form would be clearer:
```
params
```
→
```
parameters
```
Inconsistent terminology:
```
ESQL
```
should be standardized to
```
ES|QL
```

3. Content quality issues:

Vague titles that could be more specific based on description content
Absent
```
description
```
when title is self-explanatory is fine; only flag present descriptions that repeat the title, say "See PR", or add no context
Implementation-focused phrasing instead of user-visible outcomes
Verb-form split: Titles use base-form imperative (
```
Fix
```
,
```
Add
```
). Descriptions,
```
impact
```
, and
```
action
```
use third-person present (
```
Fixes
```
,
```
Adds
```
). Flag past tense (
```
Fixed
```
,
```
Added
```
) and base-form openings in descriptions
Directory mode: Flag mixed past/present description tense across files in the same run

4. YAML formatting issues (cross-reference with Step 2):

Unquoted text containing special characters (see Step 2 for details)
Inconsistent formatting across text fields

5. UI element formatting issues:

Unclear UI labels: Button names, page titles, tabs should be in "quotation marks" if the phrase is unclear. For example: 'Fix "View in AI Assistant" button availability'
Incorrectly quoted feature names: Feature names should be capitalized, not quoted (Machine Learning, not "Machine Learning")
Missing backticks: Field names, parameters, API endpoints should use
```
backticks
```
UI vs feature uncertainty: Flag when formatting choice between UI label and feature name is unclear

6. Type-title alignment issues:

Flag when changelog

type

and

title

verb patterns don't align, indicating potential misclassification:

bug-fix
/
regression
misalignment: Title uses
```
Improve
```
,
```
Enable
```
,
```
Update
```
,
```
Enhance
```
instead of expected
```
Fix
```
,
```
Resolve
```
,
```
Correct
```
- Warning: Type suggests fixing broken behavior, but title implies improvement/addition
- Suggest: Review whether behavior was actually broken or if this should be
```
enhancement
```
bug-fix
/
regression
enhancement verbs: On
```
bug-fix
```
, flag titles starting with
```
Default
```
,
```
Reserve
```
,
```
Ensure
```
, or
```
Close
```
without
```
Fix
```
bug-fix
/
regression
preventive/restrictive framing: Flag titles that describe a new restriction or validation rather than the user-visible failure, especially when the title does NOT start with
```
Fix
```
,
```
Resolve
```
, or
```
Correct
```
- Leading patterns to flag:
```
Don't
```
  ,
```
Do not
```
  ,
```
Disallow
```
  ,
```
Prevent
```
  ,
```
Reject
```
  ,
```
Block
```
  ,
```
Forbid
```
  ,
```
Prohibit
```
  ,
```
Restrict
```
  ,
```
No longer allow
```
- Warning: Title explains what is now blocked, not what was broken (recovery failure, query error, cluster red, etc.)
- Suggest: Rewrite as
```
Fix [symptom] when [condition]
```
  — e.g. "Don't allow runtime fields to shadow index sort fields" → "Fix shard recovery failures when runtime fields shadow index sort fields"
- Type note: If the change only adds validation with no prior user-visible failure, consider
```
enhancement
```
  instead of
```
bug-fix
```
enhancement
misalignment: Title uses
```
Fix
```
,
```
Resolve
```
,
```
Correct
```
instead of expected
```
Improve
```
,
```
Update
```
,
```
Optimize
```
,
```
Enable
```
,
```
Expand
```
,
```
Enhance
```
- Warning: Type suggests improving working functionality, but title implies fixing broken behavior
- Suggest: Review whether behavior was broken (→
```
bug-fix
```
  ) or truly an optimization (keep
```
enhancement
```
  )
feature
misalignment: Title uses
```
Fix
```
,
```
Improve
```
for substantial new capabilities
- Warning: Major new functionality should use
```
Add
```
  ,
```
Introduce
```
  ,
```
Enable
```
  ,
```
Support
```
- Suggest: Review scope - substantial new capability (→
```
feature
```
  ) vs minor addition (→
```
enhancement
```
  )
docs
misalignment: Title doesn't focus on documentation clarity/accuracy
- Warning: Documentation changes should use
```
Update
```
  ,
```
Add
```
  ,
```
Clarify
```
  ,
```
Document
```

Example patterns to flag:

Type
```
bug-fix
```
+ "Improve query approximation accuracy..." → Flag alignment mismatch
Type
```
bug-fix
```
+ "Don't allow runtime fields to shadow fields used in index sort" → Flag preventive framing + verb mismatch
Type
```
enhancement
```
+ "Fix Painless score scripts..." → Flag alignment mismatch
Type
```
enhancement
```
+ "Fix ES|QL performance issues..." → Flag alignment mismatch

7. Technical content issues:

Flag overly technical titles that focus on implementation details rather than user impact:

Implementation-focused titles: Class names, method names, or internal processes without user context
- Warning: Title focuses on code changes rather than user-visible symptoms
- Example: "Fix splitValue nullability coercion when constructing ColorSeries" → Flag as too technical
- Suggest: Rewrite to describe user-visible impact like "Fix inline charts with grey time series for ES|QL queries"
Technical jargon without context: Multiple technical terms that don't explain user experience
- Warning: Title requires deep technical knowledge to understand user impact
- Suggest: Focus on what users see, not how code works
Missing user symptoms: Describes internal fixes without explaining external effects
- Warning: Users can't determine if this change affects them
- Suggest: Include user-facing symptoms or feature areas affected
Preventive vs corrective: On
```
bug-fix
```
/
```
regression
```
, if the title lacks symptom words (fail, error, crash, leak, hang, timeout, incorrect, missing, red, unallocated) and instead uses restriction words (allow, disallow, prevent, reject, validate, block), flag as likely preventive framing — soft heuristic for human review, not auto-fail
Dev/test language: Flag
```
Repro and fix
```
phrasing and PR-title passthrough with class/method names
Unexpanded dev acronyms: Flag and expand per the
```
docs-fix-changelog
```
Step 4 item 2 table (do not copy the table here)
ES|QL function tokens: When
```
areas
```
includes
```
ES|QL
```
, flag unbackticked function names (
```
UNION_BY_NAME
```
,
```
JSON_EXTRACT
```
, etc.)

Eligibility (report only — never delete files):

Recommend removal when linked PR/issue is test-only, refactor-only, or internal plumbing with no user-visible change
Without PR context: flag title/description mentioning test-only work or internal refactor
Report under
```
### Recommend removal
```
; do not modify or delete files

Type-specific:

```
breaking-change
```
:
```
impact
```
and
```
action
```
are REQUIRED — flag as errors if absent;
```
subtype
```
is strongly recommended
```
deprecation
```
and
```
known-issue
```
:
```
impact
```
and/or
```
action
```
are recommended — flag as warnings if absent
```
feature
```
/
```
enhancement
```
: title/description should explain what users can now do, not how it was built
```
bug-fix
```
/
```
regression
```
: title/description should explain what was wrong and what is now correct
When present,
```
description
```
must add context beyond repeating the title; flagging "See PR" or "Internal refactoring" as low-value
```
impact
```
if present: should explain scope and who is affected
```
action
```
if present: should provide clear, prescriptive steps

这些是警告。事实来源是

sources

中链接的 changelog 风格指南。

所有类型：

标题以动词原形的动作动词开头（
```
Add
```
、
```
Fix
```
、
```
Improve
```
、
```
Remove
```
、
```
Update
```
等），而不是第三人称形式（
```
Adds
```
、
```
Fixes
```
）
标记：标题没有以声明类型所认可的原形动词开头（名词短语式标题）
标记以否定式祈使动词开头的标题：
```
Don't
```
、
```
Do not
```
——这些不是任何类型认可的首词动词
标记以名词短语或动名词开头的标题：
```
Ability to
```
、
```
Adding
```
、
```
Changing
```
、
```
Using
```
、
```
Shutdown
```
标记标题中使用斜杠分隔的枚举项（
```
foo/bar/baz
```
）
标题应具体，不能过于宽泛（“Bug fixes”或“Performance improvements”过于宽泛）
标题应避免仅包含内部引用（“PR #123”或“bug #456”）——这类标题对用户没有帮助
标题和描述应避免以实现为中心的措辞（应描述用户影响，而不是代码变更）
标题超过 80 个字符或描述超过 600 个字符 → 质量警告（属于指导原则；超出不超过 20 个字符时优先级较低；绝不作为合并阻塞项）

系统性模式警告：

1. 标题标准化问题（来自权威的 Title cleanup checklist）：

去除开发标签： 删除
```
feat:
```
、
```
fix:
```
、
```
Fix:
```
、
```
auto-implement:
```
、
```
ES|QL|DS
```
、
```
Aggs:
```
、
```
GPU codec:
```
、
```
DiskBBQ -
```
等前缀，以及
```
Bugfix -
```
等末尾 tracker 片段
禁止仅含方括号的团队标签： 将
```
[Security Solution]
```
、
```
[Query Rules]
```
、
```
[Inference]
```
等替换为面向用户的直接表述
使用有力动词： 优先使用 Improve validation for...，而不是 Better validation for...（使用现在时祈使式：Fix、Add、Remove）
不要埋没关键信息： 如果标题过于宽泛，应将描述中的具体信息融入标题，使发布说明脱离上下文也能独立理解
Product/surface 上下文： 标题如果限定于某个 UI 元素或工作流，必须明确说明变更发生的位置：
```
[Verb] [change] [in/on/for] [feature, app, page, tab, flyout, or integration]
```
。标记缺少上下文的通用名词（
```
button
```
、
```
metrics
```
、
```
monitors
```
）。可使用 PR 路径或标签、
```
areas
```
以及 issue 标题作为上下文来源
动词原形要求： 使用
```
Fix
```
、
```
Add
```
、
```
Remove
```
，而不是第三人称形式
```
Fixes
```
、
```
Adds
```
、
```
Removes
```
句首大写： 遵循标准句首大写规则
Feature/app 前缀模式： 标记需要融入上下文的
```
[Feature/App]: [Action]
```
模式标题（例如，“File upload: Fix bug”应将 feature 上下文自然融入标题）。技术术语、API 引用和代码标识符除外

2. 技术术语增强问题：

类名、方法名、配置键、API endpoint 或代码标识符缺少反引号
应使用 US English 的英式拼写：
```
serialise
```
→
```
serialize
```
、
```
colour
```
→
```
color
```
未展开的缩写本可通过完整形式表达得更清楚：
```
params
```
→
```
parameters
```
术语不一致：
```
ESQL
```
应统一为
```
ES|QL
```

3. 内容质量问题：

标题过于宽泛，而描述中包含可用于具体化标题的信息
如果标题本身已能解释清楚，则缺少
```
description
```
是可以接受的；仅当已存在的描述重复标题、只写“See PR”或未提供任何上下文时才进行标记
使用以实现为中心的措辞，而不是以用户可见结果为中心的措辞
动词形式区分： 标题使用原形祈使式（
```
Fix
```
、
```
Add
```
）。描述、
```
impact
```
和
```
action
```
使用第三人称现在时（
```
Fixes
```
、
```
Adds
```
）。标记描述中的过去式（
```
Fixed
```
、
```
Added
```
）和原形开头
目录模式： 标记同一次运行中不同文件的描述时态混用过去式和现在式的情况

4. YAML 格式问题（参见第 2 步）：

未加引号的文本包含特殊字符（参见第 2 步中的详细信息）
文本字段之间的格式不一致

5. UI 元素格式问题：

UI 标签不清晰： 如果按钮名称、页面标题或选项卡名称的含义不明确，应放在“引号”中。例如：'Fix "View in AI Assistant" button availability'
功能名称引号使用错误： 功能名称应大写并保持首字母形式，不应加引号（Machine Learning，而不是 "Machine Learning"）
缺少反引号： 字段名、参数和 API endpoint 应使用
```
backticks
```
UI 与 feature 之间的不确定性： 如果无法确定应使用 UI 标签格式还是 feature 名称格式，则进行标记

6. Type-title 对齐问题：

当 changelog 的

type

与标题动词模式不一致时进行标记，这可能表明分类有误：

bug-fix
/
regression
错位：标题使用
```
Improve
```
、
```
Enable
```
、
```
Update
```
、
```
Enhance
```
，而不是预期的
```
Fix
```
、
```
Resolve
```
、
```
Correct
```
- 警告： 类型表明是在修复损坏的行为，但标题暗示这是改进或新增功能
- 建议： 审查该行为实际上是否已经损坏，或者是否应改为
```
enhancement
```
bug-fix
/
regression
增强类动词：对于
```
bug-fix
```
，标记以
```
Default
```
、
```
Reserve
```
、
```
Ensure
```
或
```
Close
```
开头且未使用
```
Fix
```
的标题
bug-fix
/
regression
预防性或限制性表述：标记描述新增限制或验证、而不是用户可见故障的标题，尤其是标题未以
```
Fix
```
、
```
Resolve
```
或
```
Correct
```
开头的情况
- 需要标记的前导模式：
```
Don't
```
  、
```
Do not
```
  、
```
Disallow
```
  、
```
Prevent
```
  、
```
Reject
```
  、
```
Block
```
  、
```
Forbid
```
  、
```
Prohibit
```
  、
```
Restrict
```
  、
```
No longer allow
```
- 警告： 标题解释的是现在禁止了什么，而不是之前出现了什么故障（恢复失败、查询错误、集群 red 等）
- 建议： 改写为
```
Fix [symptom] when [condition]
```
  ——例如，“Don't allow runtime fields to shadow index sort fields” → “Fix shard recovery failures when runtime fields shadow index sort fields”
- 类型提示： 如果该变更仅添加验证且此前没有用户可见故障，应考虑使用
```
enhancement
```
  而不是
```
bug-fix
```
enhancement
错位：标题使用
```
Fix
```
、
```
Resolve
```
、
```
Correct
```
，而不是预期的
```
Improve
```
、
```
Update
```
、
```
Optimize
```
、
```
Enable
```
、
```
Expand
```
、
```
Enhance
```
- 警告： 类型表明是在改进正常工作的功能，但标题暗示是在修复损坏的行为
- 建议： 审查该行为是否已经损坏（→
```
bug-fix
```
  ），或者是否确实属于优化（保留
```
enhancement
```
  ）
feature
错位：标题使用
```
Fix
```
、
```
Improve
```
，但变更属于重要的新能力
- 警告： 重要新功能应使用
```
Add
```
  、
```
Introduce
```
  、
```
Enable
```
  、
```
Support
```
- 建议： 审查范围——重要新能力（→
```
feature
```
  ）还是小型新增功能（→
```
enhancement
```
  ）
docs
错位：标题未聚焦于文档的清晰度或准确性
- 警告： 文档变更应使用
```
Update
```
  、
```
Add
```
  、
```
Clarify
```
  、
```
Document
```

需要标记的示例模式：

类型
```
bug-fix
```
+ “Improve query approximation accuracy...” → 标记对齐不匹配
类型
```
bug-fix
```
+ “Don't allow runtime fields to shadow fields used in index sort” → 标记预防性表述与动词不匹配
类型
```
enhancement
```
+ “Fix Painless score scripts...” → 标记对齐不匹配
类型
```
enhancement
```
+ “Fix ES|QL performance issues...” → 标记对齐不匹配

7. 技术内容问题：

标记过度关注实现细节、而不是用户影响的标题：

以实现为中心的标题： 类名、方法名或内部流程缺少用户上下文
- 警告： 标题关注代码变更，而不是用户可见的症状
- 示例： “Fix splitValue nullability coercion when constructing ColorSeries” → 标记为过于技术化
- 建议： 改写为描述用户可见影响，例如“Fix inline charts with grey time series for ES|QL queries”
缺少上下文的技术术语： 使用多个技术术语，却没有解释用户体验
- 警告： 标题需要深厚的专业知识才能理解用户影响
- 建议： 关注用户看到的结果，而不是代码的运作方式
缺少用户症状： 描述内部修复，却没有说明外部影响
- 警告： 用户无法判断此变更是否会影响自己
- 建议： 包含用户可见的症状或受影响的功能领域
预防性还是纠正性： 对于
```
bug-fix
```
/
```
regression
```
，如果标题缺少症状词（fail、error、crash、leak、hang、timeout、incorrect、missing、red、unallocated），却使用限制词（allow、disallow、prevent、reject、validate、block），则标记为可能采用了预防性表述——这是供人工审查的软性启发式规则，不是自动失败条件
开发/测试语言： 标记
```
Repro and fix
```
类措辞，以及直接沿用 PR 标题并包含类名或方法名的标题
未展开的开发缩写： 按照
```
docs-fix-changelog
```
第 4 步第 2 项中的表格标记并展开（此处不要复制该表格）
ES|QL 函数 token： 当
```
areas
```
包含
```
ES|QL
```
时，标记未使用反引号的函数名（
```
UNION_BY_NAME
```
、
```
JSON_EXTRACT
```
等）

适用性判定（仅报告——绝不删除文件）：

如果关联的 PR/issue 仅涉及测试、仅涉及重构，或只是没有用户可见变更的内部管道工作，则建议删除
如果没有 PR 上下文，而标题或描述提到仅测试的工作或内部重构，则进行标记
在
```
### Recommend removal
```
下报告；不要修改或删除文件

按类型区分：

```
breaking-change
```
：
```
impact
```
和
```
action
```
为必需字段——缺少时标记为错误；强烈建议提供
```
subtype
```
```
deprecation
```
和
```
known-issue
```
：建议提供
```
impact
```
和/或
```
action
```
——缺少时标记为警告
```
feature
```
/
```
enhancement
```
：标题和描述应说明用户现在可以做什么，而不是功能是如何构建的
```
bug-fix
```
/
```
regression
```
：标题和描述应说明之前存在什么问题，以及现在如何得到修正
存在
```
description
```
时，它必须提供标题之外的上下文；标记“See PR”或“Internal refactoring”等低价值描述
存在
```
impact
```
时，应说明影响范围和受影响的用户群体
存在
```
action
```
时，应提供清晰且具有指导性的操作步骤

Step 5: Formatting checks

第 5 步：格式检查

These are warnings. Check

description

impact

, and

action

field values for formatting consistency.

Link formatting:

Bare URLs used as link text — should use
```
[descriptive text](url)
```
instead
Generic link text like "click here" or "read more" — should be descriptive of the destination

Code formatting:

Code fences without a language identifier — e.g.
```
```
```
with no language tag (use
```
yaml
```
,
```
json
```
,
```
bash
```
,
```
console
```
, etc.)
Field names, config keys, commands, class names, or API endpoints written as plain text — should use inline backticks
Missing backticks around obvious code identifiers like method names, parameter names, or specific values

Text formatting:

Inconsistent spelling (should follow US English conventions)
Inconsistent terminology

这些是警告。检查

description

、

impact

和

action

字段值的格式一致性。

链接格式：

将裸 URL 直接用作链接文本——应改用
```
[descriptive text](url)
```
“click here”或“read more”等通用链接文本——应使用能够描述目标内容的文本

代码格式：

代码围栏缺少语言标识符——例如
```
```
```
没有语言标签（应使用
```
yaml
```
、
```
json
```
、
```
bash
```
、
```
console
```
等）
字段名、配置键、命令、类名或 API endpoint 使用纯文本——应使用行内反引号
明显的方法名、参数名或特定值等代码标识符缺少反引号

文本格式：

拼写不一致——应遵循 US English 规范
术语不一致

Step 6: Report

第 6 步：报告

Produce one section per file reviewed. Omit empty sections. Use this format:

markdown

undefined

为每个审查的文件生成一个章节。省略空章节。使用以下格式：

markdown

undefined

Changelog review: <filename>

Summary

N schema errors, M quality warnings, P formatting warnings

N schema errors, M quality warnings, P formatting warnings

Schema errors

```
field
```
: description of the problem

```
field
```
: description of the problem

Quality warnings

```
field
```
: description of the problem

```
field
```
: description of the problem

Formatting warnings

```
field
```
: description of the problem

```
field
```
: description of the problem

Recommend removal

Optional; include only when eligibility checks fire — reason and PR/issue reference if available


If a file has no issues, say so explicitly.

Optional; include only when eligibility checks fire — reason and PR/issue reference if available


如果某个文件没有任何问题，请明确说明。

Confidence Assessment

置信度评估

Include this section when resource loading or validation has limitations:

Canonical guidance: [✓ Loaded successfully | ✗ Failed - using embedded patterns]
Repository config: [✓ Found docs/changelog.yml | ✗ Not found - using generic validation]
Validation confidence: [High | Medium | Low] - [Brief reason]
Review limitations: [Any factors affecting review accuracy]

End with a one-line overall summary across all files reviewed. If any files have quality warnings (including systematic pattern issues, type-title alignment mismatches, and technical content issues) or formatting warnings, suggest running

docs-fix-changelog

to get specific improvement suggestions that address the same patterns this review identified.

Sync awareness: If Step 1 successfully loaded canonical guidance and you detected significant discrepancies between the live documentation and this skill's embedded patterns, flag this in your summary. Note which patterns may need updating and suggest checking the canonical source directly at https://www.elastic.co/docs/contribute-docs/content-types/changelogs.

当资源加载或验证存在限制时，包含以下章节：

权威指导： [✓ 已成功加载 | ✗ 加载失败——正在使用内置模式]
仓库配置： [✓ 已找到 docs/changelog.yml | ✗ 未找到——正在使用通用验证]
验证置信度： [高 | 中 | 低]——[简要原因]
审查限制： [任何影响审查准确性的因素]

最后用一行概括所有已审查文件的整体情况。如果任何文件存在质量警告（包括系统性模式问题、type-title 对齐不匹配和技术内容问题）或格式警告，请建议运行

docs-fix-changelog

，以获取针对本次审查发现的相同模式的具体改进建议。

同步感知： 如果第 1 步成功加载了权威指导，并且发现实时文档与内置于此 skill 的模式之间存在明显差异，请在摘要中进行标记。说明哪些模式可能需要更新，并建议直接查看权威来源：https://www.elastic.co/docs/contribute-docs/content-types/changelogs。