跳转到内容
pstack 中文学习站

statechart

你在看 pstack 0.15.30 时的版本,最新版在这里

这张图画的是应用用户看到的东西。PM 读它来判定这样的行为对不对。每个状态用屏幕上的内容命名,比如「Paying」。每一步用用户做的事、或看到发生的事命名,比如「tap Pay」或「the charge goes through」。标签里不要出现变量名和动作名。脚本把这个用户叫作读者(reader),比如 readerActions 和 reader steps。

运行 node <skill dir>/scripts/statechart.mjs --help 看命令说明和图的读法。在仓库之外的临时目录里干活。命令把生成的文件写在输入文件旁边。

已经有 TLA+ 模型,或者代码具体得足以建模,用 from-spec。还没有模型,而且应该让 PM 先认可行为、再有人写代码或改代码,用 from-chart。

代码已经有 TLA+ 规格时,从这份规格的副本开始。把用户看得到的变量加进去,保留规格已有的不变量。要拿代码对照这份规格做审计,就让副本按代码的实际行为建模,把没动过的规格作为 --against 传入。用作者说能通过的那份配置检查它,并把那份配置作为 --against-config 传入,除非配置用的就是规格的文件名。一份映射同时标注两个模型,所以状态和步骤只能从两个模型都有的变量命名。在代码模型或新规格里,每个变量和动作都要绑到审查者能打开的代码上,名字取自那段代码。每个动作在代码里是不可分割的一步。动作的每个条件,把检查它的代码的文件和行号写进这个条件的注释,例如 \* pay.ts:120。

  1. 选定图的状态。PM 关心的事屏幕上看不到时,比如屏幕还显示「Paying」却被扣了第二次款,状态就命名为「Paying, charged twice」。先从少的状态开始,只有拆分能把两个 bug 分开时才拆。
  2. PM 认可的每条规则写成一个不变量,PM 的原话作为它的注释。每条规则要说出用户在屏幕上看到什么、或从请求得到什么,以及能改变它的代码。缺一样的规则就拒绝。有的规则要等一切落定之后才成立,这时定义 Settled == ~ENABLED System,其中 System 是用户不会做的那些动作的析取。被打破的规则都报成 bug。永远不要为了让图通过而弱化规则。
  3. 运行 from-spec,然后填它写出的映射文件。标签放进 state 和 step,用户的动作按动作名列进 readerActions。两个 bug 经不同的代码路径停在同一个屏幕时,加上 cause,让它指出代码路径。要按 PM 关心的事给状态着色,比如「Toast shown」,就从 group 返回这个分组。图例会写出各个分组,违反规则的状态仍带红边。
  4. 有还没合入的修复时,从代码为它建模,把这个模型作为 --fixed 传入。
  5. 每张图都用 --png 渲染,并逐张查看 PNG。检查每条编号路径是否按顺序读得通。标签读起来像代码,就修好 state 或 step,再跑一遍命令。
  6. 对照真实代码重放每个 bug 的经过,写成测试或现场复现,模型里一个动作对应一步。只驱动用户或客户端能到达的入口,只断言他们看得到的东西。断言自己设下的标志、或者在源码文本里查找的测试,什么也证明不了。一次运行证明了经过的一部分、读代码证明了其余部分时,说明各自证明了哪部分。测试复制了无法导入的代码时,给出复制内容的提交和行范围,并列出复制漏掉了什么。bug 复现不了,就假定是模型错了,直到你能证明并非如此。修模型,不修规则。
  1. 画出 PM 认可的那张图。每件独立变化的东西各占一个分区,比如连接和同步角标。每条规则加一行 %% never,写上 PM 的原话。「the app closes」画成一条边,指向用户接下来看到的状态。
  2. 运行 from-chart。规则被打破,就是商定的图有设计 bug。把这个 bug 拿给 PM。
  3. 把真实代码的守卫和变量加进 from-chart 写出的规格,再跑一遍 from-chart。它打印的每处差异,都问 PM 是代码错了,还是图需要修正。

把每张图的 PNG 和 Mermaid 源码交给 PM。每个 bug 写一行:违反哪条规则、按图上的编号是哪几步、是否复现、那个还没合入的修复能不能修好它。用了 --against 时,还要说明规格是否已经列出它:在 stories.md 点名的配置里、在规格关于模型略去了什么的说明里,还是根本没列。命令列出的条件中没有文件和行号时,不要报告规则成立。引用的每个数字都取自 summary.json。附上 stories.md 和能重新生成一切的命令。说明模型略去了什么。