diff --git a/design/dev/doc-conventions.md b/design/dev/doc-conventions.md index 718353db..f410f6d4 100644 --- a/design/dev/doc-conventions.md +++ b/design/dev/doc-conventions.md @@ -139,22 +139,27 @@ ``` **现状**:现在缺什么、为什么是问题(关键处带 file:line 或文档指针)。工程直入条目必须在现状里指认证据(bug 证据或工程债条目)。 -**缺口**:还差哪一次设计讨论/哪份设计产物才能写卡。仅当状态为 待文档设计/文档设计中/待美术设计/美术设计中 时此属性必须存在;轨闭合后必须删除。 +**缺口**:还差哪一次设计讨论/哪份设计产物才能写卡。尚有未闭合的设计轨时此属性必须存在;全部设计轨闭合后删除。 **归属**:主责系统文档或线别。 **状态**:按状态机取词。 ``` -状态机按标题里的设计面分轨,状态一律取下例用词: +状态机按标题里的设计面分轨,状态一律取下例用词。状态行按**状态段累积制**书写:条目每推进一段,就把新状态段接在状态行末尾,段与段用+号连接,书写顺序=推进顺序;已过去的段一律保留、禁删——闭合凭据要留在行内,编排四查与开工核验拿它比对。每段各自按状态词白名单与凭据规则校验,+号只作状态段连接符。 ``` -文档轨:待文档设计 → 文档设计中 → 文档设计已闭合 - (凭据=文档路径+版本号,例:文档设计已闭合(design/gdd/systems/xxx.md v1.2)) -美术轨:待美术设计 → 美术设计中 → 美术设计已闭合 - (凭据=样张过审+art-bible 条款版本) -双轨条目:两串状态用+号并列(例:文档设计已闭合(…v0.6)+美术设计中) -轨闭合后下游共用:待写卡 → 已写卡(design/research/ 下的卡片路径)→ 已编迭代 N → 完成即整条删除 +各轨推进序列(双轨条目设计阶段两段并列推进,一文档轨一美术轨): +文档轨:待文档设计 → 文档设计中 → 文档设计已闭合(凭据=文档路径+版本号, + 例:文档设计已闭合(design/gdd/systems/xxx.md v1.2)) +美术轨:待美术设计 → 美术设计中 → 美术设计已闭合(凭据=样张过审、art-bible 条款版本, + 例:美术设计已闭合(样张过审、art-bible v3.x)) +双轨条目设计阶段示例:文档设计已闭合(design/gdd/systems/xxx.md v0.6)+美术设计中 +进入下游段(待写卡及之后)的前置条件——双轨:两个设计轨段都在场且都已闭合(带凭据);单轨:本轨闭合段(带凭据)在场 +下游共用序列:待写卡 → 已写卡(design/research/ 下的卡片路径)→ 已编迭代 N → 完成即整条删除 +单轨累积示例(已编迭代):文档设计已闭合(design/gdd/systems/xxx.md v1.2)+已写卡(design/research/xxx.md)+已编迭代 2 ``` +凭据括号内禁用+号——+只作状态段连接符,凭据内需要并列多项时用顿号(如上例「样张过审、art-bible v3.x」),用+会被流水线闸误判为状态段。已编迭代 N 段的交叉核依据=同状态行内「已写卡」段括号里的卡片路径。 + 三条特殊通道: | 设计面 | 通道规则 | @@ -179,7 +184,7 @@ roadmap 由顶部里程碑表+迭代总表组成,迭代总表一行一个迭 | 状态 | 待开工 / 进行中 / 已完成(YYYY-MM-DD)/ 已终止(YYYY-MM-DD) | | 需求卡片 | 只写文件路径;一格内一行一卡,格内排列顺序=执行顺序;已退役填保留字「已退役(git 历史可考)」 | | 编入时间 | YYYY-MM-DD(该迭代最近一次编入卡片的日期) | -| 预计周期 | ≈N 周(0.5 步进,N ≤ 2) | +| 预计周期 | ≈N 周(0.5 步进,N ≤ 2);超过 2 周须随带日期的用户特批标记(格式见 12.4),流水线闸见标记放行、无标记判红 | | 实现报告 | `reports/iterN-实现报告-YYYY-MM-DD.md`;未完成=「—」;退役=「已退役(git 历史可考)」 | 迭代行禁入内容:事项说明、卡序叙述、T 段明细、读数、闸数字、裁点记录、门依赖。卡间依赖写在卡片自身,行内只放上表六列的事实。特批标记同样可用于 roadmap 格(须带日期,见 12.4)。