oss-issue-triage
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseOSS Issue Triage
OSS Issue 分类处理(Triage)
You design the system that decides how a project's incoming issues and pull requests get handled - labels, intake, response promise, duty rotation, closing rules - sized to the capacity the maintainers actually have.
The queue is not out of control because the labels are wrong. It is out of control because inflow exceeds available attention and no written rule says what happens to the difference. Make that arithmetic explicit, then design around it.
Machine-generated submissions broke one side of it in 2025. RedMonk's Kate Holterhoff named the asymmetry for security reports (May 2026): "generating a plausible-sounding vulnerability report now costs pennies in tokens. Evaluating whether it's real still costs an hour of expert time." Inflow is no longer bounded by human effort while triage capacity still is, so every design needs a planned answer for volume, not only for classification.
Do not triage individual items, curate the first-contribution queue, review code, or handle conduct incidents. Route those elsewhere:
- First-contribution path, good first issues: samber/developer-relations-skills@oss-contributor-onboarding
- Repeat questions into docs: samber/developer-relations-skills@developer-troubleshooting-docs
- Hostile behaviour: samber/developer-relations-skills@developer-community-moderation
- Who decides scope: samber/developer-relations-skills@oss-governance
- The wider measurement framework: samber/developer-relations-skills@developer-community-health
你设计的系统决定了项目收到的 issue 和 pull request 如何处理——标签、入口、响应承诺、轮值制度、关闭规则——并且这些设计要与维护者实际拥有的精力容量匹配。
队列失控不是因为标签错了。失控是因为流入量超过了可用的注意力,而且没有成文规则说明多出来的部分会怎样。把这个算术关系显式化,然后围绕它进行设计。
2025 年,机器生成的提交打破了其中一侧。RedMonk 的 Kate Holterhoff 在 2026 年 5 月点明了安全报告中的这种不对称性:“现在生成一份听起来可信的漏洞报告只需要几美分的 token;而评估它是否真实仍然需要专家一小时的时间。”流入量不再受人类投入的约束,而分类处理能力仍然是——因此每个设计都需要对“量”给出计划中的应对,而不仅仅是对“分类”给出方案。
不要做这些事:对单个条目进行分类、整理首次贡献队列、审查代码或处理行为事件。请将它们路由到其他地方:
- 首次贡献路径、good first issues:samber/developer-relations-skills@oss-contributor-onboarding
- 重复问题转文档:samber/developer-relations-skills@developer-troubleshooting-docs
- 不友好行为:samber/developer-relations-skills@developer-community-moderation
- 谁决定范围:samber/developer-relations-skills@oss-governance
- 更广泛的度量框架:samber/developer-relations-skills@developer-community-health
Interview
访谈(Interview)
Ask one at a time, multiple-choice where you can, skipping what the user already answered. Questions 1-6 gate everything; without them you design a process for an imaginary project.
- What is the effort ceiling: how many people triage today, how many hours a week can each give in a bad month, and may anyone add triagers or change tracker settings?
- Is there a date this has to hold by - a release, an audit, a response target already published to someone?
- Do you want this backlog cleared, or a system that still works next year with different maintainers?
- How large is the queue: open issues, open external pull requests, age of the oldest?
- What does the inflow look like - mostly bug reports, feature requests, or usage questions?
- Is the project volunteer-run, company-backed, or mixed, and does anyone have a contractual response obligation?
- Which tracker, can you change labels, templates and automation on it, and what exists today (labels, templates, contributing guide, bots)?
- Do external pull requests count as triage work here, or does a separate review process own them?
- Has the share of low-quality or machine-generated submissions grown in the last year, and can you estimate it?
- Where do security reports arrive today - the public tracker, a private channel, or nowhere defined?
- Where should usage questions go instead - a forum, a chat, discussions, nowhere yet?
- Who may close an issue, who decides what is out of scope, and what made you open this now?
If question 1 answers effectively zero hours, stop designing and say so: the honest deliverable is a reduced intake plus a published "this project is in maintenance mode" statement, not a taxonomy nobody will apply.
Answers to 1, 2 and 3 re-rank every menu below; say which moved what.
- Hard date: promotes what acts this week (shorten the promise, chooser routing, the direction check); demotes anything paying off over a quarter.
- "Still works next year": promotes adding triagers and validated forms, both of which lose on ratio inside any single month.
- Low effort ceiling: deletes options rather than demoting them - with no authority to add people, add-triagers is not a lever and must not appear in the deliverable.
一次问一个问题,尽可能提供多选,已经回答过的问题就跳过。问题 1-6 是所有后续的前提;没有它们,你只是在为一个虚构的项目设计流程。
- 人力上限是多少:现在有多少人做分类处理,在状态最差的月份每人每周能投入多少小时,是否允许任何人新增 triager 或修改 tracker 设置?
- 是否存在一个必须支撑到的时间点——发布、审计、或者已经对外公布的响应目标?
- 你是想清空这个积压队列,还是想要一个明年换成不同维护者后仍然能运转的系统?
- 队列有多大:开放的 issue 数、开放的外部 pull request 数、最老条目的年龄?
- 流入是什么样的——主要是 bug 报告、功能请求还是使用问题?
- 项目是志愿者运营、公司支持还是混合模式?是否有人承担合同约定的响应义务?
- 用哪个 tracker?你能修改其上的标签、模板和自动化吗?目前已经有什么(标签、模板、贡献指南、机器人)?
- 外部 pull request 算不算这里的分类处理工作,还是由单独的审查流程来负责?
- 过去一年中,低质量或机器生成的提交占比是否增加?你能估计一下吗?
- 安全报告目前会到达哪里——公开 tracker、私有渠道,还是根本没有定义?
- 使用问题应该改去哪里——论坛、聊天、discussions,还是还没有去处?
- 谁可以关闭 issue?谁决定哪些超出范围?是什么促使你现在开始处理这件事?
如果问题 1 的回答实际上为零小时,停止设计并直接说明:诚实的交付物是一个缩减后的入口,外加一份公开的“此项目处于维护模式”声明,而不是一套没有人会使用的标签体系。
问题 1、2、3 的回答会重新排序下面的每个选项;要说明是哪个回答导致了什么变化。
- 硬性截止日期:会提升那些本周就起作用的做法(缩短承诺、chooser 路由、方向检查);降低那些需要超过一个季度才能见效的事情的优先级。
- “明年还能运转”:会提升“新增 triager”和“表单校验”,但这两者在任何单个月份内的性价比都不占优。
- 人力上限很低:要删除选项而不是降低优先级——如果没有权限增加人手,“新增 triager”就不是一个可用的杠杆,绝不能出现在交付物中。
Step 1 - Measure the queue before changing it
步骤 1 - 在改动之前先度量队列
Export the tracker's issues and run the baseline; every later decision references these numbers.
bash
gh issue list --state all --limit 2000 \
--json number,title,state,createdAt,updatedAt,closedAt,labels,author,comments > issues.json
python3 scripts/triage-baseline.py issues.json --triage-prefix "kind/,priority/"
python3 scripts/triage-baseline.py issues.json --stale-days 120 --format json > baseline.jsonIt reports, from JSON arrays, JSON Lines or CSV:
- open count
- age median/p90
- untriaged share
- inactive count
- median and p90 time to first human response
- created-versus-closed flow
- label usage, including single-use labels
Without a scriptable environment, sample 50 open items by hand and estimate the same numbers - an estimate beats designing blind, and without a baseline you cannot tell whether the redesign worked.
Read the numbers back before proposing anything: a queue that is 80% usage questions needs a different intervention from one that is 80% unanswered bug reports.
Then ask what the per-item framing hides: do these items cluster? On a large stale backlog, grouping issues by shared root cause under a tracking issue and redirecting the rest to it often clears more queue than triaging item by item. Decide per-item versus clustering here, before designing the per-item machinery.
导出 tracker 中的 issue 并运行基线统计;后面的每个决策都会引用这些数字。
bash
gh issue list --state all --limit 2000 \
--json number,title,state,createdAt,updatedAt,closedAt,labels,author,comments > issues.json
python3 scripts/triage-baseline.py issues.json --triage-prefix "kind/,priority/"
python3 scripts/triage-baseline.py issues.json --stale-days 120 --format json > baseline.json它会从 JSON 数组、JSON Lines 或 CSV 中报告:
- 开放数量
- 年龄中位数/p90
- 未分类比例
- 非活跃数量
- 首次人工响应的中位数和 p90 时间
- 创建与关闭的流量对比
- 标签使用情况,包括一次性标签
如果没有可脚本化的环境,就手工抽取 50 个开放条目并估计同样的数字——有估计总比盲目设计强;没有基线,你无法判断重新设计是否奏效。
在提出任何方案之前先把数字读回去:80% 是使用问题的队列,与 80% 是未回复 bug 报告的队列,需要完全不同的干预方式。
然后问:以单个条目为单位的视角隐藏了什么?这些条目是否成群出现? 在大量陈旧积压中,把具有共同根因的 issue 归并到一个 tracking issue 之下,并把其余条目重定向过去,往往比逐条分类处理能清理更多队列。在开始设计逐条处理机制之前,先在这里决定采用逐条处理还是聚类处理。
Step 2 - Do the capacity arithmetic
步骤 2 - 计算容量算术
Multiply triagers × sessions per week × minutes per session ÷ minutes per item, and compare against the baseline's inflow.
Do not import a minutes-per-item constant. Time the pilot session in step 9 and use the project's own number; until then, three minutes is a planning placeholder this skill sets, not a measured industry figure. Deep investigation is not triage - it is work triage schedules.
When capacity is below inflow, no label scheme fixes it. Three levers close the gap; pick by queue relieved per maintainer hour, not by which is quickest to type:
- efficiency: cut intake > shorten the promise > add triagers
- effort: shorten the promise (rewrite one line, defend it once) > cut intake (a day of forms and chooser configuration) > add triagers (recruit, grant permissions, calibrate - a quarter before a new triager is net positive)
- value: cut intake (permanently lowers the left side of the arithmetic) > add triagers (the only lever that raises capacity at all) > shorten the promise (nothing improves; the promise merely stops being broken)
- compliance cost: cut intake == add triagers (tied because both are internal decisions with no external counterparty) > shorten the promise where question 6 found a contractual obligation, since there the published target is a commitment and shortening it is a contract change
Efficiency starves adding triagers - the only lever that raises capacity, and the slowest to pay. Promote it whenever the project expects to still exist in a year: one that only ever cuts intake shrinks itself to fit its worst month. State the chosen lever in the deliverable so the user is not surprised in three months.
Decide the volume-gating trigger now, while nothing is on fire: the inflow rate or valid-report share at which the project will restrict who may open items, cap open submissions per author, or change the incentives that attract volume. Projects that adopted gating reached for it only after burnout was acute; deciding the trigger at design time makes it policy instead of crisis improvisation. ./references/worked-examples.md walks curl's collapse to a one-in-twenty valid share through this arithmetic, and shows why its answer acted on the economics of submitting rather than the speed of triage.
Set the first-response target from the capacity number, not from ambition - a human reply, not a fix and not a bot greeting. The arithmetic, volunteer-versus-company-backed differences and contractual obligations: ./references/policy-and-metrics.md.
计算:triager 人数 × 每周会话次数 × 每次会话分钟数 ÷ 每条条目分钟数,然后与基线的流入量比较。
不要直接引入“每条条目分钟数”的常数。在步骤 9 中对试点会话计时,并使用项目自己的数字;在此之前,三分钟只是本 skill 设定的规划占位值,不是经过测量的行业数据。深度调查不是 triage——triage 是安排工作,不是完成工作。
当容量低于流入量时,任何标签方案都解决不了问题。有三个杠杆可以弥合差距;选择依据是“每维护者小时能缓解多少队列”,而不是哪个写起来最快:
- 效率:削减入口 > 缩短承诺 > 新增 triager
- 人力:缩短承诺(改写一行,为一句话辩护一次)> 削减入口(一天的表单和 chooser 配置)> 新增 triager(招募、授权、校准——新 triager 要一个季度才能 net positive)
- 价值:削减入口(永久降低算术的左侧)> 新增 triager(唯一能提升容量的杠杆)> 缩短承诺(什么都不会改善;承诺只是不再被打破)
- 合规成本:削减入口 == 新增 triager(平手,因为两者都是内部决策,没有外部对手方)> 缩短承诺——当问题 6 发现存在合同义务时,因为此时公布的目标是一种承诺,缩短它就是合同变更
效率维度会饿死“新增 triager”这个选项——它是唯一能提升容量的杠杆,却也是回报最慢的。只要项目预期一年后仍然存在,就应该提升它的优先级:一个只会削减入口的项目,会把自己缩到只能适配最糟糕月份的大小。在交付物中明确说明所选杠杆,这样用户三个月后不会感到意外。
趁还没火烧眉毛,现在就定下量级门控触发条件(volume-gating trigger):即当流入速率或有效报告占比达到某个阈值时,项目将限制谁能开启条目、限制每个作者可提交的开放数量,或改变吸引量的激励机制。已经采用门控的项目,都是在倦怠已经严重之后才想起它;在设计时定下触发条件,会让它成为政策,而不是危机中的即兴反应。./references/worked-examples.md 通过这套算术说明了 curl 是如何跌到“每 20 条只有 1 条有效”的程度,以及为什么它的对策作用于“提交的经济学”而不是“分类的速度”。
根据容量数字来设定首次响应目标,而不是根据雄心——目标是人工回复,不是修复,也不是机器人问候。相关算术、志愿者与公司支持项目的差异、合同义务:见 ./references/policy-and-metrics.md。
Step 3 - Design the label taxonomy
步骤 3 - 设计标签体系
Build labels as orthogonal axes - type, state, priority, area, contributor-facing - with at most one value per axis on any item. State moves the queue; priority starts arguments, so keep it as small as the project can bear.
Size the set against the reference points in ./references/published-findings.md:
- ten default labels on a new repository
- five state roles plus two categories in the most-installed triage skill
- six prefixed families at Kubernetes scale
Mapping those onto a project is this skill's judgment, not a sourced rule: the honest answer usually sits between the first two and approaches the third only when ownership is genuinely split.
Two rules come from PyTorch's taxonomy - the only documented running in production, on PyTorch's own main repository:
- Gate labelling on confidence. Apply a label at high or medium confidence; at low confidence apply a "needs review" state instead of guessing. A guessed area label sends the item to the wrong owner and costs more than no label.
- Never let automation apply the top priority level. Route every candidate for it to human confirmation instead. Priority is the axis with the most downstream consequence and the least machine-checkable definition.
Axes, sized starter sets, naming rules, cleaning up an existing label mess without erasing history, the allowlist-and-validation pattern, and tracker mechanics: ./references/label-taxonomy.md.
Present the taxonomy for approval before touching the tracker - one imposed on maintainers who did not agree to it decays within a month.
把标签构建成正交的轴——类型、状态、优先级、领域、面向贡献者——每条目在每个轴上至多一个值。状态推动队列前进;优先级会引发争论,所以要控制在项目能承受的最小规模。
根据 ./references/published-findings.md 中的参考点来设定规模:
- 新仓库上的十个默认标签
- 安装量最高的 triage skill 中的五个状态角色加两个类别
- Kubernetes 规模下的六个带前缀的标签族
把这些映射到具体项目上是本 skill 的判断,而不是有出处的规则:诚实的答案通常介于前两者之间,只有在职责真正分散在多个团队时才接近第三个。
有两条规则来自 PyTorch 的标签体系——这是唯一有文档记载的生产环境运行案例,就在 PyTorch 自己的主仓库中:
- 用置信度给标签应用设门槛。 在高或中等置信度时才应用标签;低置信度时应用“needs review”状态,而不是猜测。猜一个领域标签会把条目送到错误的负责人手中,代价比不加标签更大。
- 永远不要让自动化应用最高优先级。 把所有候选都转给人工确认。优先级是下游影响最大、又最缺乏机器可检查定义的一个轴。
轴、规模合适的起步标签集、命名规则、如何清理现有标签混乱而不抹去历史、allowlist 与校验模式,以及 tracker 机制:见 ./references/label-taxonomy.md。
在改动 tracker 之前,先把标签体系提交审批——强加给并未同意的维护者的体系,一个月内就会瓦解。
Step 4 - Cut the intake
步骤 4 - 削减入口流量
Capacity spent on items that should never have arrived is the largest reclaimable block. Rank the four cuts by triage minutes reclaimed per hour of setup - no compliance-cost axis applies, since none of the four creates an obligation to anyone:
- efficiency: chooser routing > validated forms > disabling blank issues > auto-applied type label
- effort: disabling blank issues == auto-applied type label (one setting, one line of form YAML) > chooser routing (needs a destination that may not exist yet) > validated forms (one form per real category, written, tested and revised when reporters skip fields)
- value: chooser routing (removes whole categories instead of speeding them up) > validated forms (turns two round-trips into one submission on every bug report, forever) > disabling blank issues (closes the bypass that makes forms optional) > auto-applied type label (one axis, seconds an item)
- Chooser routing - usage questions to a forum or chat, commercial requests to a sales contact. A stopping condition: a routed report never reaches the tracker, so steps 5-8 never touch it.
- Validated forms replacing markdown templates. Require exactly the fields that change the outcome; every optional field a reporter skips teaches them the form is decorative.
- Disable blank issues once the forms cover the real categories.
- Auto-applied type label from the form, plus the issue type where the tracker has one.
Efficiency starves option 2: highest recurring value, most setup, so a maintainer with one free evening does the toggles instead and the round-trips continue. Promote it to first when bug reports dominate inflow, where that cost is paid on every item. A project with nowhere to route usage questions (question 12) has no option 1 - delete it from this pass rather than listing it as pending work.
Security reports leave the tracker entirely. Every mature project examined runs the same three-element pipeline, separate from general triage:
- a private intake channel
- a named, size-capped response team
- an embargo mechanism for coordinated disclosure
Apache instructs committers never to enter vulnerability details in a public tracker. With no security list, the code host's private vulnerability reporting is the default.
Form capabilities, chooser configuration, the full security path and the volume-gating options: ./references/issue-intake-and-routing.md - read it before writing form YAML.
花在根本不该到达的条目上的精力,是最大的可回收部分。按“每小时的搭建成本能回收多少 triage 分钟”来排列四种削减手段——这里不适用合规成本维度,因为四种都不会对任何人产生义务:
- 效率:chooser 路由 > 表单校验 > 禁用空白 issue > 自动应用类型标签
- 人力:禁用空白 issue == 自动应用类型标签(一个设置、一行表单 YAML)> chooser 路由(需要一个可能还不存在的目的地)> 表单校验(每个真实类别一个表单,编写、测试并在报告人跳过必填字段时修订)
- 价值:chooser 路由(移除整个类别,而不是加速它们)> 表单校验(在每个 bug 报告上都把两次往返变成一次提交,而且永远有效)> 禁用空白 issue(封死让表单变得可选的绕过通道)> 自动应用类型标签(一个轴,每条只花几秒)
- Chooser 路由 - 把使用问题引导到论坛或聊天,商业请求引导到销售联系人。一条终止条件:被路由走的报告永远不会进入 tracker,因此步骤 5-8 不会接触到它。
- 表单校验 取代 Markdown 模板。只要求那些会改变结果的字段;报告人每跳过的一个可选字段,都让他们学会“这个表单是装饰品”。
- 禁用空白 issue,一旦表单覆盖了真实类别。
- 自动应用类型标签,从表单中读取,并在 tracker 支持的地方一并设置 issue 类型。
效率维度会饿死选项 2:它有最高的重复价值,也有最高的搭建成本,所以只有一晚上空闲的维护者会改几个开关,然后让往返继续发生。当 bug 报告主导流入时,把它提升到第一位,因为这时每条条目都在付出这个成本。如果项目没有地方可路由使用问题(问题 12),就不存在选项 1——从本轮中删除,而不是列为待办工作。
安全报告完全离开 tracker。 每一个被考察的成熟项目都运行着同一条三要素流水线,与常规分类处理分离:
- 私有入口渠道
- 指定且人数上限固定的响应团队
- 用于协同披露的 embargo 机制
Apache 指示 committer 绝不能在公开 tracker 中输入漏洞细节。如果没有安全邮件列表,代码托管平台的私有漏洞报告功能是默认选择。
表单能力、chooser 配置、完整安全路径和量级门控选项:见 ./references/issue-intake-and-routing.md——在写表单 YAML 之前先读它。
Step 5 - Assign the duty
步骤 5 - 分配值班职责
An unowned process is not a process.
- Name who triages, in a rotation with a stated shift length (a week is the common unit) and a named backup. Mozilla's two-tier model is the most robust documented pattern: a long-term triage owner accountable per component, plus a triage duty rotating weekly that does the work.
- Fix a cadence and a stop rule: a session ends at its time box, not at inbox zero, so triage survives a spike.
- Set the session order: newest untriaged first (protects the response target), then items where the reporter replied, then a fixed backlog quota.
- Grant triage-level permissions rather than commit access - most trackers have a role for labelling, closing and assigning without write access, which is how a triage team grows past the committers.
- Define the escalation: what a triager decides alone, what waits for a maintainer, how long that wait may be.
Three things decide whether a recurring triage meeting survives:
- a queue view built for it
- asynchronous pre-triage, so the meeting is decision-making rather than first contact
- decisions recorded as label or state changes rather than only in minutes
Rust's compiler triage meeting is the clearest example: a Zulip stream pre-triages and priority is set by replacing a label, so the output stays queryable.
没有负责人的流程不是流程。
- 明确谁做分类处理,采用有明确轮换周期(通常是一周)的轮值制度,并指定备份人。Mozilla 的两层模型是有文档记载的最稳健模式:长期 triage owner 对每个组件负责,外加每周轮换的 triage duty 来执行具体工作。
- 固定节奏和停止规则:一次分类会话在时间盒结束时结束,而不是在收件箱清零时才结束,这样 triage 才能在突发流量中存活。
- 设定会话顺序:最新的未分类条目优先(保护响应目标),然后是报告人回复过的条目,最后是固定的积压配额。
- 授予 triage 级权限,而不是 commit 权限——大多数 tracker 都有无需写权限即可打标签、关闭和指派的角色,这正是 triage 团队能扩展到 committer 之外的方式。
- 定义升级路径:triager 可以单独决定什么,什么需要等待维护者,这个等待最多可以多久。
三件事决定一个定期 triage 会议能否存活:
- 为它构建的队列视图
- 异步预分类,让会议做决策而不是首次接触
- 决策记录为标签或状态更改,而不仅仅写在会议纪要中
Rust 编译器团队的 triage 会议是最清晰的例子:Zulip 流中完成预分类,优先级通过替换标签来设置,因此结果始终保持可查询。
Step 6 - Give pull requests their own gate order
步骤 6 - 给 Pull Request 自己的关卡顺序
A pull request carries hard automated checks an issue never has; do not reuse the issue process.
Two gates are not menu items, since both are automated preconditions that fire before a human looks:
- sign-off (CLA or DCO)
- CI permission for externally authored PRs
Nothing merges without sign-off, because the licence provenance it records is the project's only account of where the code came from.
Rank the three gates that spend maintainer attention by rejections settled per minute of reviewer time - not cheapest first, which buries the direction question under the machinery:
- efficiency: direction check ("does this belong in the project") > size-based risk label > code-correctness review
- effort: direction check (a minute on title, description and linked issue) > size-based risk label (computed from the diff, but it only sorts) > code-correctness review (the expensive pass this order exists to protect)
- value: code-correctness review (the only gate that can accept a change) > direction check (settles the rejections that were never about code) > size-based risk label (routes; decides nothing)
- compliance cost: direction check == size label (tied: a maintainer reading a description and a bot measuring a diff both leave the project owing nothing) > code-correctness review (accepting a change makes the project answerable for its provenance and security posture, which is what sign-off documents)
The direction check leads because roughly two-thirds of rejected agentic PRs never needed the code read at all - the MSR 2026 mining study's breakdown of 353 manually inspected rejections is in ./references/published-findings.md.
Efficiency starves the code-correctness review: highest value, highest effort, permanently last. Promote it to first when a trusted repeat contributor sends a small change against an already-accepted issue - the direction question is answered before the PR opens, and running the order costs more than the read.
The per-item decision path, reply templates with weak/strong pairs, the PR deltas and the rejection knowledge base are in ./references/response-playbook.md.
Pull request 带有 issue 永远没有的硬性自动化检查;不要复用 issue 流程。
两个关卡不是可选项,因为它们都在人工查看之前就会触发的自动化前置条件:
- 签署(CLA 或 DCO)
- 外部作者 PR 的 CI 权限
没有签署就不能合并,因为它记录的许可证来源是项目唯一能说明代码来源的证据。
按“每分钟评审时间解决多少拒绝”来排序三个消耗维护者注意力的关卡——不要按成本最低优先,那样会把方向问题埋在机械化流程之下:
- 效率:方向检查(“这个改动属于项目吗”)> 基于规模的 risk 标签 > 代码正确性审查
- 人力:方向检查(标题、描述和关联 issue 各看一分钟)> 基于规模的 risk 标签(从 diff 计算,但它只是排序)> 代码正确性审查(本顺序要保护的昂贵环节)
- 价值:代码正确性审查(唯一能接受改动的关卡)> 方向检查(解决那些从来与代码无关的拒绝)> 基于规模的 risk 标签(用于路由;不决定任何事)
- 合规成本:方向检查 == 规模标签(平手:维护者读描述和机器人量 diff,都不让项目背上义务)> 代码正确性审查(接受改动让项目对其来源和安全姿态负责,这一点正是签署流程要记录的)
方向检查领先,是因为被拒绝的 agentic PR 中大约三分之二根本不需要读代码——MSR 2026 挖掘研究对 353 个人工检查的拒绝案例的分解见 ./references/published-findings.md。
效率维度会饿死代码正确性审查:价值最高、成本最高、永远排在最后。当受信任的重复贡献者针对已经被接受的 issue 提交一个小改动时,把它提升到第一位——方向问题在 PR 开启前就已回答,此时按关卡顺序走一遍比直接读代码更贵。
逐条决策路径、带有弱/强配对的回复模板、PR 差异和拒绝知识库,见 ./references/response-playbook.md。
Step 7 - Write the closing and staleness policy
步骤 7 - 编写关闭与过期政策
Decide explicitly what closes automatically and what never does. The defensible line: auto-close only items waiting on a reporter who stopped replying; never one waiting on the maintainers - a confirmed bug closed by a bot tells the reporter their evidence was worthless.
Configure the sweep:
- restrict it to the waiting-on-reporter state only
- exempt the confirmed and blocked states
- warn before closing
- run the first pass in dry-run mode, so the blast radius is known before it fires
Every close carries a reason and says how to reopen.
Anchor each clock to a named waiting party rather than to the item in the abstract. Kubernetes' published clocks, the sweep configuration, and when a one-time backlog bankruptcy is legitimate: ./references/policy-and-metrics.md.
明确决定什么会自动关闭、什么永远不会。站得住脚的界线是:只自动关闭那些等待某个不再回复的报告人的条目;绝不自动关闭等待维护者的条目——一个已确认 bug 被机器人关闭,等于告诉报告人他们提供的证据毫无价值。
配置清理扫描:
- 只限制在“等待报告人”状态
- 豁免“已确认”和“被阻塞”状态
- 关闭前给出警告
- 第一次运行使用 dry-run 模式,以便在真正触发前知道影响范围
每次关闭都附带原因,并说明如何重新打开。
把每个时钟锚定到具名的等待方,而不是笼统地锚定到条目本身。Kubernetes 的公开时钟、扫描配置,以及一次性积压清零(backlog bankruptcy)在何时是合理的:见 ./references/policy-and-metrics.md。
Step 8 - Automate classification, never the first reply
步骤 8 - 自动化分类,但永远不自动化首次回复
Automate the mechanical layer first, deterministically:
- fill the area label from changed paths
- apply the type from the form
- request review from the owning team
- run the staleness clock
Every documented machine-learning triage deployment keeps a human as final decision-maker: treat model assistance as a scoring and suggestion layer, never an autonomous accept, reject or close.
Copy two patterns before considering any classifier:
- Automate who is on duty, not what to decide. Mozilla syncs the triage-owner field to whoever is on the rotation calendar, so requests reach the person actually working rather than piling on one name.
- Hold the label set as a validated artifact, so automation cannot invent labels or overwrite human work - mechanics in .
label-taxonomy.md
Leave the first human sentence to a human. Response metrics exclude bot replies by definition and reporters discount them the same way; an auto-greeting followed by three weeks of silence makes the wait worse. When an agent posts triage comments, disclose it in the comment.
先用确定性方式自动化机械层:
- 从变更路径填充领域标签
- 从表单应用类型
- 向负责团队请求评审
- 运行过期时钟
每个有文档记载的机器学习 triage 部署都保留人类作为最终决策者:把模型辅助当作评分和建议层,绝不要让它自主 accept、reject 或 close。
在考虑任何分类器之前,先复制两个模式:
- 自动化“谁在值班”,而不是“决定什么”。 Mozilla 会将 triage-owner 字段与轮值日历中的人同步,因此请求会到达实际当班的人,而不是堆在一个人名下。
- 把标签集视为经过校验的工件,这样自动化就不能发明标签或覆盖人工工作——机制见 。
label-taxonomy.md
把第一句属于人的话留给人。响应指标按定义排除机器人回复,报告人也同样不把它们当回事;自动问候之后跟着三周沉默,只会让等待更难受。当 agent 发布 triage 评论时,在评论中公开说明这是 agent。
Step 9 - Publish, run a pilot pass, measure
步骤 9 - 发布、运行试点、度量
Publish the policy:
- write it into the repository, next to the contributing guide
- link it from the intake forms
- announce the change once, in the project's own channel
Run one real triage session with the user against the new system on 15-20 items, and time it. That produces the minutes-per-item figure step 2 deferred and exposes what the design got wrong - a missing state, an ambiguous label, a reply template that does not fit. A policy never executed once is a draft.
Re-run monthly for the first quarter, and iterate against three starting targets. All three are this skill's self-set baselines, not industry benchmarks - replace each with the project's own measured trend once a quarter of data exists:
triage-baseline.py- Untriaged share below 10% of open items.
- Published first-response target met on at least 90% of items.
- Net inflow at or below zero over the quarter.
Iterate until they hold, or lower the published promise to one that does.
Never read a count metric alone. CHAOSS's guidance restricts these measures to activity "primarily driven by humans", and, under machine-generated volume, closure ratios and time-to-close can improve while real maintainer burden rises. Pair every count with a human-driven signal: first response with bots and author self-replies excluded, and how many people could cover triage if one person left.
With persistent memory available, store the durable decisions:
- capacity numbers
- the agreed response target
- the label axes and their definitions
- categories routed off the tracker
- the volume-gating trigger
- declared out-of-scope requests
The next review is a diff against those.
发布政策:
- 写进仓库,放在贡献指南旁边
- 从入口表单链接到它
- 在项目自己的渠道中公布一次这个变更
与用户一起,在新系统上对 15-20 个条目运行一次真实的 triage 会话,并计时。这会产出步骤 2 推迟计算的“每条分钟数”,并暴露设计中的错误——某个缺失的状态、一个有歧义的标签、一个不合适的回复模板。从未执行过一次的政策只是草稿。
第一季度每月重新运行 triage-baseline.py,并对照三个起步目标迭代。这三个都是本 skill 自行设定的基线,不是行业基准——一旦有了一个季度的数据,就用项目自己的度量趋势替换每个目标:
- 未分类比例低于开放条目的 10%
- 已公布的首次响应目标至少在 90% 的条目上达成
- 季度内净流入量等于或低于零
迭代直到这些目标成立,或者把公布的承诺降到一个能成立的承诺。
绝不要只读一个计数指标。CHAOSS 的指南将这些指标限定为“主要由人类驱动的”活动;在机器生成的量下,关闭比例和关闭时间可能改善,而维护者的实际负担却在上升。把每个计数指标与一个人驱动的信号配对:排除机器人和作者自回复后的首次响应,以及如果有一人离开,还能有几个人能覆盖 triage。
如果有持久化记忆可用,请存储这些长期决策:
- 容量数字
- 达成一致的响应目标
- 标签轴及其定义
- 被路由到 tracker 之外的类别
- 量级门控触发条件
- 声明为超出范围的需求
下次审视就是对它们的 diff。
Invocation examples
调用示例
| The user says | You produce |
|---|---|
| "We have 900 open issues and no idea where to start" | Run the baseline, read it back in plain language, then make the per-item-versus-clustering call - no taxonomy yet |
| "Design a triage process for our maintainer team" | All five deliverable artefacts, in order, validated one by one |
| "Our labels are a mess, redo them" | Label usage counts first, then a change list of create/rename/merge/delete with one definition and one axis per label |
| "Should we turn on a stale bot?" | The waiting-on-reporter-only rule, a dry-run first pass, and the exempt-state list - plus a refusal to sweep maintainer-owned items |
| "Nobody answers PRs from outside contributors" | The gate order from step 6 and a separate PR response target - not the issue process reused |
| "We are drowning in AI-generated reports" | The volume-gating trigger from step 2, intake economics, and the platform controls - before any classifier |
| 用户说 | 你应该产出 |
|---|---|
| “我们有 900 个开放 issue,完全不知道从哪开始” | 运行基线,用平实的语言读回结果,然后做出“逐条处理 vs 聚类处理”的判断——先不涉及标签体系 |
| “为我们的维护者团队设计一个 triage 流程” | 按顺序产出全部五个交付物,并逐一验证 |
| “我们的标签一团糟,重新做” | 先统计标签使用情况,再给出一份 create/rename/merge/delete 变更清单,每个标签一条定义和一个轴 |
| “我们应该开启 stale bot 吗?” | 只针对“等待报告人”的规则、首次 dry-run 扫描、豁免状态列表——外加拒绝清理维护者拥有的条目 |
| “没人回复外部贡献者的 PR” | 来自步骤 6 的关卡顺序和单独的 PR 响应目标——而不是复用 issue 流程 |
| “我们被 AI 生成的报告淹没了” | 来自步骤 2 的量级门控触发条件、入口经济学和平台控制——先于任何分类器 |
Deliverable
交付物
Produce these five artefacts in order, each validated with the user before the next - never all in one silent pass:
- Baseline - step 1's numbers, the one-line reading of them, and the per-item-versus-clustering call.
- Triage policy - the published document: what belongs in the tracker, the response target, the states and their meanings, when items close, who triages, the volume-gating trigger. Template in ./references/policy-and-metrics.md.
- Label change list - create, rename, merge, delete, each with a one-sentence definition and its axis.
- Intake change list - forms to add or rewrite with required fields, chooser routing entries, the security path, automation to enable, each with the triage minutes it should save.
- Duty and gate design - the rotation with named people and shift length, the escalation rule, the pull-request gate order.
Keep every artefact in the project's own vocabulary - real label strings, real channels, real maintainer names.
按顺序产出这五个工件,每个都要先与用户验证再做下一个——绝不能一次性静默完成全部:
- 基线(Baseline) - 步骤 1 的数字、对它们的一句话解读,以及“逐条处理 vs 聚类处理”的判断。
- Triage 政策 - 公开文档:什么属于 tracker、响应目标、状态及其含义、条目何时关闭、谁做分类、量级门控触发条件。模板见 ./references/policy-and-metrics.md。
- 标签变更清单 - create、rename、merge、delete,每个都带一句话定义和所属轴。
- 入口变更清单 - 需要新增或重写的表单及必填字段、chooser 路由条目、安全路径、要启用的自动化,每个都注明应节省的 triage 分钟数。
- 值班与关卡设计 - 指名道姓的轮换和班次长度、升级规则、pull-request 关卡顺序。
让每个工件都使用项目自己的词汇——真实的标签字符串、真实的渠道、真实的维护者姓名。
Failure modes
失败模式
Each row names a failure the steps do not already spell out; the fix is the whole row.
| Failure | Fix |
|---|---|
| Aspirational target - "24-hour response" from two volunteers | Publish the number the baseline supports |
| Dormant rotation - a documented rota nobody has run in a year | Give it an owner and a liveness check; retire it loudly if it lapses |
Priority theatre - everything is | Two or three levels, defined by consequence |
| Big-bang migration - new labels, old forms, old saved views | Migrate labels, forms, views and automation in one pass |
| Triage as fixing - a session spent debugging one item | Time-box the pass; triage schedules work; it is not the work |
| Unmeasured redesign - new process, no idea whether it helped | Re-run the baseline monthly |
每一行都指出步骤中尚未明确写出的一个失败模式;修复方法是整行所描述的行动。
| 失败 | 修复 |
|---|---|
| 目标过于理想——“两名志愿者承诺 24 小时响应” | 发布基线支持的响应数字 |
| 轮值形同虚设——有一份文档化的轮值表但一年没人运行 | 给它一个负责人和存活检查;如果失效,公开宣布该轮值退役 |
优先级作秀(priority theatre)——所有东西都是 | 只设置两到三级,按后果定义 |
| 大爆炸式迁移——新标签、旧表单、旧的已保存视图 | 把标签、表单、视图和自动化一次性迁移完 |
| 把 triage 当成修复——一次会话用来调试某一条 | 给会话设置时间盒;triage 安排工作,而不是做工作 |
| 无度量的重新设计——新流程上线,却不知道是否有效 | 每月重新运行基线 |
References
参考
- ./references/label-taxonomy.md - axes, starter sets, cleanup procedure, tracker mechanics.
- ./references/issue-intake-and-routing.md - form fields, chooser, off-tracker routing, security path.
- ./references/response-playbook.md - per-item decision path, reply templates, rejection knowledge base.
- ./references/policy-and-metrics.md - capacity arithmetic, policy template, closing rules, measurement plan.
- ./references/worked-examples.md - a worked capacity read and a positive/negative rotation pair.
- ./references/published-findings.md - which figures are sourced and which are self-set baselines.
- ./references/label-taxonomy.md - 轴、起步标签集、清理流程、tracker 机制。
- ./references/issue-intake-and-routing.md - 表单字段、chooser、tracker 外路由、安全路径。
- ./references/response-playbook.md - 逐条决策路径、回复模板、拒绝知识库。
- ./references/policy-and-metrics.md - 容量算术、政策模板、关闭规则、度量计划。
- ./references/worked-examples.md - 一个完整的容量读取示例,以及一组正/负轮值对比。
- ./references/published-findings.md - 哪些数字有出处、哪些是自行设定的基线。