stale-sweep

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Stale Sweep (mcp-toolbox)

陈旧项巡检(mcp-toolbox)

This repo runs no stale bot (
.github/
has no stale workflow), so closing is always a deliberate maintainer act. The value of a sweep is therefore not the list of old things, which anyone can get by sorting on a date. It's the judgment about which silences belong to the contributor, which belong to us, and which are the backlog working as intended.
此仓库未运行 stale bot(
.github/
中没有 stale workflow),因此关闭始终是维护者有意识的操作。巡检的价值不在于列出旧条目——按日期排序谁都能做到——而在于判断哪些沉默应由贡献者负责、哪些应由我方负责,以及哪些只是 backlog 按预期运作。

Goal

目标

Given a window (default 60 days), deliver a sweep the maintainer can work through in one sitting: every candidate sorted into close / nudge-author / on-us / leave-alone, each with the date and reason that put it there, plus a paste-ready comment wherever one is warranted.
给定一个时间窗口(默认 60 天),交付维护者一次会话即可处理完的巡检结果:每个候选都归入 close / nudge-author / on-us / leave-alone,附上促成该归类的日期和理由,并在适用处提供可直接粘贴的评论。

Prerequisites

前置条件

  • gh
    authenticated for
    googleapis/mcp-toolbox
    . A GitHub MCP server substitutes: the commands below map to its read/list tools.
  • A window. If the maintainer didn't give one, default to 60 days and say that's what you used.
  • gh
    已针对
    googleapis/mcp-toolbox
    完成认证。也可以使用 GitHub MCP server 替代:以下命令可映射到其 read/list tools。
  • 一个时间窗口。如果维护者未指定,则默认使用 60 天,并明确说明所用窗口。

Workflow

工作流

Step 1: Read the source of truth

第 1 步:读取事实来源

Read these live, not from memory.
  • references/maintainer-playbook.md: authoritative for the
    60-day silence rule on
    status: waiting for response
    /
    status: feedback wanted
    , the SLO response and closure targets, and the canonical comment templates.
  • gh label list --repo googleapis/mcp-toolbox --limit 200
    : there is no
    stale
    label
    , so never propose one. This workflow's vocabulary is
    status: waiting for response
    ,
    status: feedback wanted
    ,
    duplicate
    , and
    wontfix
    .
  • .github/blunderbuss.yml
    : which
    product:
    label routes to which team, needed to name an owner on anything blocked on us.
实时读取以下内容,不要依赖记忆。
  • references/maintainer-playbook.md:对于
    status: waiting for response
    /
    status: feedback wanted
    超过 60 天无响应的规则、SLO 响应与关闭目标,以及标准评论模板而言,这是权威依据。
  • gh label list --repo googleapis/mcp-toolbox --limit 200
    :不存在
    stale
    标签
    ,因此绝不能建议添加。本工作流使用的标签词汇为
    status: waiting for response
    、
    status: feedback wanted
    、
    duplicate
    和
    wontfix
    。
  • .github/blunderbuss.yml
    :该文件定义了哪个
    product:
    标签对应哪个团队;当我方处于阻塞状态时,需要据此指定负责人。

Step 2: Pull the candidates

第 2 步:获取候选项

bash
CUTOFF=$(date -d '60 days ago' +%F 2>/dev/null || date -v-60d +%F)   # GNU, then BSD/macOS

gh search issues --repo googleapis/mcp-toolbox --state open --updated "<$CUTOFF" \
  --limit 100 --json number,title,url,updatedAt,createdAt,labels,author,commentsCount

gh search prs --repo googleapis/mcp-toolbox --state open --updated "<$CUTOFF" \
  --limit 100 --json number,title,url,updatedAt,labels,author,isDraft
gh search
defaults to 30 results, so always pass
--limit
.
bash
CUTOFF=$(date -d '60 days ago' +%F 2>/dev/null || date -v-60d +%F)   # GNU, then BSD/macOS

gh search issues --repo googleapis/mcp-toolbox --state open --updated "<$CUTOFF" \
  --limit 100 --json number,title,url,updatedAt,createdAt,labels,author,commentsCount

gh search prs --repo googleapis/mcp-toolbox --state open --updated "<$CUTOFF" \
  --limit 100 --json number,title,url,updatedAt,labels,author,isDraft
gh search
默认返回 30 条结果,因此始终要传入
--limit
。

Step 3: Don't let
updatedAt
decide

第 3 步:不要让
updatedAt
决定归类

updatedAt
is not a silence measure. Label edits, bot comments, renovate rebases, and cross-references all bump it, so an item a bot has kept warm never enters the candidate list at all despite nobody having looked at it in months. Get the real last-human-touch before judging anything:
bash
gh issue view <n> --repo googleapis/mcp-toolbox --json comments,labels,assignees,createdAt \
  --jq '.comments[-3:] | map({author: .author.login, at: .createdAt, body: .body[0:200]})'
Discount label-only churn and bot comments (
gemini-code-assist
,
renovate
, release automation, the Cloud Build failure reporter). What's left is the last substantive human comment, and that date drives every call below.
When the sweep is scoped to one area rather than the whole repo, widen the search window and filter on last human comment yourself, so bot-warmed items can't hide behind the cutoff.
updatedAt
不是衡量沉默的指标。编辑标签、bot 评论、renovate rebase 和交叉引用都会更新它,因此,即使数月没人关注过,被 bot 持续更新的条目也不会进入候选项列表。在作出任何判断前,先获取真实的最后一次人类活动:
bash
gh issue view <n> --repo googleapis/mcp-toolbox --json comments,labels,assignees,createdAt \
  --jq '.comments[-3:] | map({author: .author.login, at: .createdAt, body: .body[0:200]})'
忽略仅涉及标签的变动和 bot 评论(
gemini-code-assist
、
renovate
、release automation、Cloud Build failure reporter)。剩下的最后一次实质性人类评论才是关键,其日期决定后续每项判断。
如果本次巡检的范围仅限于某个领域,而非整个仓库,应扩大搜索窗口,并自行按最后一次人类评论进行筛选,避免 bot 更新过的条目躲在截止日期之后。

Step 4: Check whether it already resolved itself

第 4 步:检查问题是否已自行解决

The highest-value step, and the one a stale bot structurally cannot do. Before drafting any nudge or close, check whether the thing fixed itself while nobody was looking:
  • git log --oneline --since=<created date> --grep=<term>
    , plus a grep for the feature or symbol.
  • For a bug, trace the code path and see whether the defect is still there.
  • Search for a newer issue that superseded it.
Either outcome leaves the stale buckets entirely, and both beat silence followed by a timeout:
  • Fixed: close as fixed in
    <sha>
    , shipped in vX.Y.Z, citing the commit. That's a real answer, not a stale close.
  • Superseded:
    duplicate
    plus a link to the newer issue.
这是价值最高的一步,也是 stale bot 在机制上无法完成的一步。在起草任何提醒或关闭建议之前,检查该事项是否已在无人关注的情况下自行解决:
  • git log --oneline --since=<created date> --grep=<term>
    ,并针对该功能或符号执行 grep。
  • 对于 bug,追踪代码路径,确认缺陷是否仍然存在。
  • 搜索是否已有取代它的新 issue。
无论出现哪种结果,都应将相应条目完全排除在 stale buckets 之外;两者都优于在沉默后直接超时处理:
  • Fixed: 以“已在
    <sha>
    修复并随 vX.Y.Z 发布”为由关闭,并引用该 commit。这才是真正的答复,而不是因为陈旧而关闭。
  • Superseded: 标记为
    duplicate
    ,并附上较新 issue 的链接。

Step 5: Sort by whose silence it is

第 5 步:按沉默责任方归类

Stale is not the same as closeable. Put every remaining candidate in exactly one bucket.
Blocked on the author. Carries
status: waiting for response
or
status: feedback wanted
, or the last comment is a maintainer question that never got a reply.
  • Past 60 days of silence: propose the close, per the playbook rule.
  • Under 60 days: propose a nudge that restates the specific outstanding question and names a close date.
Blocked on us. A report filed with enough information and no maintainer reply, or a contributor PR sitting on review or on maintainer-triggered CI.
  • Never propose closing these. Timing out work that stalled on our side is the failure mode that costs contributor trust.
  • Each one is an SLO miss, so the action is internal: name the owning team from the
    product:
    label per
    blunderbuss.yml
    , and give the SLO clock from the playbook table.
  • Surface them loudly rather than letting them sit below the close list.
Blocked on nobody. Triaged feature requests in the backlog,
status: help wanted
,
good first issue
, p2/p3 nice-to-haves.
  • Silence is the expected state here, not rot. Leave them alone.
  • Flag one only when it's gone genuinely obsolete (targets a removed source, or a design the project moved past) or when the labels are wrong.
When the bucket is a real toss-up, ask. A wrong nudge is cheap; a wrong close is not.
陈旧不等于可以关闭。将每个剩余候选项准确归入一个 bucket。
Blocked on the author. 带有
status: waiting for response
或
status: feedback wanted
,或者最后一条评论是维护者提出但一直未获回复的问题。
  • 沉默超过 60 天:根据 playbook 规则提出关闭建议。
  • 沉默不足 60 天:提出 nudge,重申具体待回复的问题,并注明关闭日期。
Blocked on us. 信息充分但维护者尚未回复的报告,或者 contributor PR 正在等待 review 或维护者触发的 CI。
  • 绝不能建议关闭这些事项。 对因我方原因而停滞的工作执行超时处理,是会损害贡献者信任的失败模式。
  • 每一项都是 SLO miss,因此应采取内部行动:根据
    blunderbuss.yml
    中的
    product:
    标签指定负责团队,并依据 playbook 表格给出 SLO 时限。
  • 应醒目呈现这些问题,而不是让它们埋在关闭列表下方。
Blocked on nobody. 已完成 triage 的 backlog feature request,以及带有
status: help wanted
、
good first issue
或 p2/p3 nice-to-have 标签的事项。
  • 在这里,沉默是预期状态,而不是失控迹象。保持原样。
  • 只有当事项确实已经过时(例如目标是已移除的源,或项目已经不再采用该设计),或者标签错误时,才需要标记。
如果某个 bucket 确实难以判断,应询问维护者。错误的 nudge 代价较低,错误的关闭则不然。

Step 6: Apply the PR-specific rules

第 6 步:应用 PR 专用规则

PRs go stale for reasons issues don't:
  • Auto-generated (
    renovate
    ,
    release-please
    ): never nudge a bot, and draft no comment. Checks green means merge; superseded by a newer bot PR means close.
  • Draft (
    isDraft
    ): silence is expected. Leave alone unless it's months old, and then only a light "still planning to pick this up?".
  • Blocked on maintainer-triggered CI: PRs from external forks can't run the integration tests, which need a maintainer's
    tests: run
    label or a
    /gcbrun
    comment. This is an on-us item wearing contributor-silence clothing, so check it before reading quiet as abandoned.
  • CLA, conflicts, or red CI: nudgeable, but name the actual blocker instead of "any update?". When a CLA check fails though the human author has signed, the usual cause is an AI co-author trailer; suggest squashing to a single human-authored commit.
  • Approved and unmerged: not stale, just unmerged. Surface separately so it gets merged.
PR 出现陈旧的原因与 issue 不同:
  • 自动生成(
    renovate
    、
    release-please
    ):绝不能提醒 bot,也不要起草评论。Checks 通过即可合并;被更新的 bot PR 取代则关闭。
  • Draft(
    isDraft
    ):沉默符合预期。保持原样,除非已经过去数月;此时也只需轻量询问:“还在计划继续处理吗?”
  • 被维护者触发的 CI 阻塞:外部 fork 提交的 PR 无法运行 integration tests,因为这些测试需要维护者添加
    tests: run
    标签或发送
    /gcbrun
    评论。这实际上是 on-us 事项,只是表现为贡献者沉默;因此,在将其解读为已被放弃之前,必须先检查这一点。
  • CLA、冲突或 CI 失败:可以 nudge,但应指出实际阻塞项,而不要只问“有任何进展吗?”。如果 CLA check 失败,但人类作者已经签署,通常原因是 AI co-author trailer;建议压缩为单个由人类编写的 commit。
  • 已批准但未合并:这不是陈旧,只是尚未合并。应单独呈现,以便尽快合并。

Step 7: Draft the comments

第 7 步:起草评论

Adapt the playbook's templates rather than inventing wording. Two shapes:
Nudge, naming the specific unanswered thing and a date:
text
Hi @<author>, following up here. We're still blocked on <the specific thing: the repro steps, the Toolbox version, a reply to the question in <link>>. If we don't hear back in the next 14 days we'll close this out, though you're welcome to comment or reopen any time after that.
Close, giving the reason, reopenability, and thanks:
text
Closing this out: we weren't able to move forward without <the missing thing>, and it's been quiet for <N> days. That's not a judgment on the report, so please comment or reopen if you're still hitting this and we'll pick it back up. Thanks for taking the time to file it!
Keep two things out of both. A form-letter tone, since these are hand-sent precisely so they don't read like a bot. And any phrasing that puts the delay on the contributor when part of it was ours.
应调整 playbook 中的模板,而不是自行编造措辞。采用以下两种形式:
Nudge,说明具体未解决的事项和日期:
text
Hi @<author>, following up here. We're still blocked on <the specific thing: the repro steps, the Toolbox version, a reply to the question in <link>>. If we don't hear back in the next 14 days we'll close this out, though you're welcome to comment or reopen any time after that.
Close,说明原因、是否可以重新开启,并表达感谢:
text
Closing this out: we weren't able to move forward without <the missing thing>, and it's been quiet for <N> days. That's not a judgment on the report, so please comment or reopen if you're still hitting this and we'll pick it back up. Thanks for taking the time to file it!
两种评论都应避免两点:一是模板化口吻——这些评论之所以由人工发送,正是为了避免读起来像 bot;二是把部分由我方造成的延迟归咎于贡献者的表述。

Rules

规则

  • Propose only. Never run
    gh issue close/comment/edit
    ,
    gh pr close/comment/merge
    , or apply a label. Deliver the sweep in chat.
  • Never close what's blocked on us. The only valid outputs there are a reply, a review, or a
    tests: run
    .
  • Only real labels: every one must appear in
    gh label list
    , and no
    stale
    label exists.
  • Show the last human comment date for every candidate, never
    updatedAt
    , so the maintainer can check your arithmetic.
  • Ground the call. A close cites the playbook rule and the silence duration; an "already fixed" cites a commit SHA or
    file:line
    ; a routing claim cites
    blunderbuss.yml
    . Mark anything you couldn't verify
    [UNVERIFIED]
    rather than asserting it.
  • Disclose the edges of the sweep: the window, the result cap if you hit it, and anything you skipped. Silence about coverage reads as "I checked everything".
  • 仅提出建议。 绝不能运行
    gh issue close/comment/edit
    、
    gh pr close/comment/merge
    或添加标签。应在聊天中交付巡检结果。
  • 绝不能关闭因我方原因而阻塞的事项。 在这些事项中,唯一有效的输出是回复、review 或
    tests: run
    。
  • 只使用真实标签: 每个标签都必须出现在
    gh label list
    中,并且不存在
    stale
    标签。
  • 对每个候选项显示最后一次人类评论的日期, 不要使用
    updatedAt
    ,以便维护者核对计算结果。
  • 让每项判断都有依据。 关闭建议需引用 playbook 规则和沉默时长;“已经修复”需引用 commit SHA 或
    file:line
    ;团队归属判断需引用
    blunderbuss.yml
    。无法核实的内容应标记为
    [UNVERIFIED]
    ,而不是直接断言。
  • 披露巡检范围边界: 包括时间窗口、达到结果上限时的情况,以及跳过的任何内容。不披露覆盖范围会被理解为“我已经检查了全部内容”。

Output format

输出格式

text
undefined
text
undefined

Stale sweep: <N>-day window (cutoff <YYYY-MM-DD>), <X> candidates

Stale sweep: <N>-day window (cutoff <YYYY-MM-DD>), <X> candidates

Already resolved, close with an answer (<n>) | # | title | resolved by | last human |
Close (author silent >60d) (<n>) | # | title | last human | what we asked for |
Nudge author (<n>) | # | title | last human | the specific ask |
On us (SLO miss, do not close) (<n>) | # | title | waiting since | owning team | SLO status |
PRs (merge or close) (<n>) | # | title | why |
Leave alone (<n>)
  • #<n>: <why the silence is fine>
Draft comments
Already resolved, close with an answer (<n>) | # | title | resolved by | last human |
Close (author silent >60d) (<n>) | # | title | last human | what we asked for |
Nudge author (<n>) | # | title | last human | the specific ask |
On us (SLO miss, do not close) (<n>) | # | title | waiting since | owning team | SLO status |
PRs (merge or close) (<n>) | # | title | why |
Leave alone (<n>)
  • #<n>: <why the silence is fine>
Draft comments

#<n>: <close | nudge | resolved>

#<n>: <close | nudge | resolved>

<paste-ready body>
Apply: gh issue comment <n> --repo googleapis/mcp-toolbox --body "..." gh issue close <n> --repo googleapis/mcp-toolbox --comment "..."

- **Empty buckets:** omit them, except **On us**, which is always stated even when empty. "Nothing
  is rotting on our side" is the line the maintainer most wants confirmed.
- **Large sweeps:** classify in batches so items don't bleed together, and lead with the counts per
  bucket. The maintainer decides how deep to go from those counts.
<paste-ready body>
Apply: gh issue comment <n> --repo googleapis/mcp-toolbox --body "..." gh issue close <n> --repo googleapis/mcp-toolbox --comment "..."

- **空 bucket:** 省略即可,但 **On us** 即使为空也必须列出。“我方没有任何事项停滞”正是维护者最希望得到确认的信息。
- **大规模巡检:** 分批分类,避免不同事项相互混淆,并优先给出各 bucket 的数量。维护者将根据这些数量决定巡检深度。