跳转到内容
contextlint

REF-003 稳定度一致性

概述

Section titled “概述”

验证某项的稳定度不超过其依赖项的稳定度。出现 stable 项目引用 experimental 项目这样的不一致时,会报告为 warning。这是项目作用域规则,会跨越 include 加载的所有文档进行评估。

为什么需要

Section titled “为什么需要”

稳定度标签(experimental / review / stable 等)表示文档内项目的可信度。如果 stable 的需求依赖 experimental 的需求,那么每当依赖项变更时 stable 一侧也需要跟进,稳定度的含义将形同虚设。反方向的依赖(experimental → stable)没有问题。本规则可机械化验证稳定度标签的一致性。

选项

Section titled “选项”
字段类型必填说明
stabilityColumnstring✓存放稳定度的列名
stabilityOrderstring[]✓稳定度的排列顺序(从不稳定到稳定)
definitionsstring✓定义 ID 的文件 glob
referencesstring[]✓引用 ID 的文件 glob 数组
idColumnstring—定义文件中存放 ID 的列名(默认值:ID)
idPatternstring—视为 ID 的值的正则表达式

stabilityOrder 按数组的索引顺序视为「越来越稳定」。["experimental", "review", "stable"] 中 stable 最稳定。引用侧行的稳定度比依赖目标项目的稳定度更稳定(索引更大)时,即视为违例。

违例

Section titled “违例”
docs/requirements.md:
| ID     | 内容             | Stability    |
| ------ | ---------------- | ------------ |
| REQ-01 | 用户注册         | experimental |


docs/design.md:
| ID     | 关联    | Stability |
| ------ | ------- | --------- |
| DSN-01 | REQ-01  | stable    |

设置 stabilityOrder: ["experimental", "review", "stable"] 时,stable 的 DSN-01 引用 experimental 的 REQ-01,因此判定为违例。

docs/design.md
  line 4  warning  Item "REQ-01" has stability "experimental" in docs/requirements.md, but is referenced from a row with stability "stable"  REF-003

修正后

Section titled “修正后”

将引用方的稳定度与依赖目标对齐,或提升依赖目标的稳定度。

docs/requirements.md:
| ID     | 内容             | Stability |
| ------ | ---------------- | --------- |
| REQ-01 | 用户注册         | stable    |

配置示例

Section titled “配置示例”
{
  "rule": "ref003",
  "options": {
    "stabilityColumn": "Stability",
    "stabilityOrder": ["experimental", "review", "stable"],
    "definitions": "**/requirements.md",
    "references": ["**/design.md", "**/tests.md"],
    "idColumn": "ID",
    "idPattern": "^REQ-\\d+$"
  }
}

相关规则

Section titled “相关规则”