Back to Details

write-bug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Write Bug (FOLIO)

编写Bug报告（FOLIO）

A FOLIO bug report must be reproducible, specific, and evidence-backed. The reader should be able to recreate the defect without guessing.
FOLIO的bug报告必须具备可复现性、明确性和证据支撑。阅读者无需猜测就能重现该缺陷。

Bug Structure

Bug报告结构

Every FOLIO bug must have these sections (in order). Sections marked (optional) are omitted when they add no value.
  1. Summary — One-line title on the Jira issue. Must name the affected area and the observable symptom. See Summary Rules.
  2. Overview / Context (recommended) — 1–3 sentences explaining the impact, origin (e.g. regression from TICKET-123), or business context. A majority of FOLIO bugs open with an "Overview:" section; include one unless the defect is truly self-evident from the summary.
  3. Preconditions — Environment, data, roles, permissions, feature flags, or prior tickets required before the steps work. Each precondition must be independently verifiable.
  4. Steps to reproduce — Numbered, atomic actions. One user action per step. No assumptions about prior navigation.
  5. Expected result — What the system should do, referencing a source of truth (spec, acceptance criteria, prior behavior) when possible.
  6. Actual result — What the system actually does. Quote error messages verbatim and include status codes/IDs where relevant.
  7. Additional information (optional but strongly recommended) — Stack traces, request/response payloads, query plans, log excerpts, screenshots, video, affected environment URLs, and reproducibility rate.
每份FOLIO bug报告都必须包含以下部分（按顺序排列）。标记为_(可选)_的部分若没有实际价值可省略。
  1. 摘要 — Jira工单的一行标题。必须指明受影响的区域和可观察到的症状。详见摘要规则。
  2. 概述/上下文 (推荐) — 1-3句话说明影响范围、来源（例如：TICKET-123的回归问题）或业务背景。大多数FOLIO bug报告都会以“概述：”部分开头；除非缺陷从摘要中就能完全一目了然，否则建议包含该部分。
  3. 前置条件 — 执行复现步骤前所需的环境、数据、角色、权限、功能标志或相关工单。每个前置条件都必须能独立验证。
  4. 复现步骤 — 编号的原子操作。每一步对应一个用户操作。不假设用户已完成之前的导航操作。
  5. 预期结果 — 系统应有的表现，尽可能参考权威来源（规格说明、验收标准、之前的正常表现）。
  6. 实际结果 — 系统实际的表现。逐字引用错误信息，并在相关情况下包含状态码/ID。
  7. 补充信息 (可选但强烈推荐) — 堆栈跟踪、请求/响应负载、查询计划、日志片段、截图、视频、受影响环境的URL，以及复现概率。

Template

模板

markdown
undefined
markdown
undefined

Overview

Overview

[1–3 sentences on impact, affected users, regression source, or related tickets. Recommended for anything non-trivial — FOLIO bugs conventionally open with this.]
[1–3 sentences on impact, affected users, regression source, or related tickets. Recommended for anything non-trivial — FOLIO bugs conventionally open with this.]

Preconditions

Preconditions

  1. [Environment / tenant / user role]
  2. [Data state — e.g. "An Order in 'Open' status exists with one PO line"]
  3. [Feature flag / configuration]
  1. [Environment / tenant / user role]
  2. [Data state — e.g. "An Order in 'Open' status exists with one PO line"]
  3. [Feature flag / configuration]

Steps to reproduce

Steps to reproduce

  1. [Single user action]
  2. [Single user action]
  3. [Single user action]
  1. [Single user action]
  2. [Single user action]
  3. [Single user action]

Expected result

Expected result

  • [Observable outcome #1]
  • [Observable outcome #2, referencing spec/AC if applicable]
  • [Observable outcome #1]
  • [Observable outcome #2, referencing spec/AC if applicable]

Actual result

Actual result

  • [Observable outcome #1, including exact error text]
  • [HTTP status / error code / record state]
  • [Observable outcome #1, including exact error text]
  • [HTTP status / error code / record state]

Additional information (optional)

Additional information (optional)

Reproducibility: [Always / Intermittent (X of Y) / Once] Environment: [folio-etesting-snapshot / folio-etesting-sprint / local] Module versions: [mod-orders 13.0.5, ui-orders 9.1.2] Affected tickets / regression source: [PROJECT-123] Workaround: [Describe any workaround found, or "None" / omit if not applicable] Test Cases: [TestRail IDs, e.g. C15189, C15190 — omit if not used by your team]
``` [paste stack trace or log excerpt] ```
Attachments: screenshots / HAR / video (attach to Jira)
undefined
Reproducibility: [Always / Intermittent (X of Y) / Once] Environment: [folio-etesting-snapshot / folio-etesting-sprint / local] Module versions: [mod-orders 13.0.5, ui-orders 9.1.2] Affected tickets / regression source: [PROJECT-123] Workaround: [Describe any workaround found, or "None" / omit if not applicable] Test Cases: [TestRail IDs, e.g. C15189, C15190 — omit if not used by your team]
``` [paste stack trace or log excerpt] ```
Attachments: screenshots / HAR / video (attach to Jira)
undefined

Summary Rules

摘要规则

A good summary passes the "scan test" — a triager can decide priority and routing from the title alone.
优秀的摘要需通过**“快速扫描测试”** —— 分类人员仅通过标题就能确定优先级和工单分配方向。

Format

格式

[<Area/Component>] <symptom> when <trigger/condition>
The 
[<Area>]
prefix is optional when the Jira project already narrows the area (e.g., UIOR implies Orders UI).
[<区域/组件>] <症状> 当 <触发条件>
若Jira项目已明确限定范围（例如：UIOR代表订单UI），则
[<区域>]
前缀可省略。

Do

注意事项（应做）

  • Name the observable symptom: "returns 500", "displays duplicate rows", "is not updated", "does not reflect the change".
  • Include the trigger: "when moving holdings", "after paying invoice in foreign currency", "on tenant with >50k orders".
  • Mention the environment only if the bug is environment-specific (e.g., "M-an dry-run |" prefix for env-specific issues).
  • 明确可观察到的症状：“返回500错误”、“显示重复行”、“未更新”、“未反映变更”。
  • 包含触发条件：“移动馆藏时”、“用外币支付发票后”、“在订单数超过5万的租户环境中”。
  • 仅当bug是环境特定时才提及环境（例如：针对环境特定问题使用“M-an dry-run |”前缀）。

Don't

注意事项（不应做）

  • Don't write vague titles: ❌ "Bug in orders", ❌ "Doesn't work".
  • Don't prescribe a fix in the title: ❌ "Add null check in X".
  • Don't over-qualify with implementation detail the triager won't know.
  • 不要写模糊的标题：❌“订单模块存在bug”、❌“无法正常工作”。
  • 不要在标题中指定修复方案：❌“在X中添加空值检查”。
  • 不要过度添加分类人员不了解的实现细节。

Examples (from real FOLIO bugs)

示例（来自真实FOLIO bug报告）

  • ✅ "Updating receiptDate does not update updatedDate in POL audit history"
  • ✅ "Order expended amount is not converting the invoice currency"
  • ❌ "POL bug"
  • ❌ "Fix currency handling"
  • ✅“更新receiptDate时未更新POL审计历史中的updatedDate”
  • ✅“订单支出金额未转换发票币种”
  • ❌“POL模块bug”
  • ❌“修复币种处理逻辑”

Writing Guidelines

编写指南

Steps to reproduce

复现步骤

  • Start from a clean, logged-in state or state it in Preconditions.
  • One action per step. Split "Open the order and click Receive" into two.
  • Be literal. Use the exact UI label or API path: 
    POST /orders/wrapper-pieces?query=...
    .
  • Reference data by property, not ID. "An Order in 'Open' status with Synchronized receiving workflow" beats "Order d4e7-...".
  • Stop at the point of failure. Don't include post-failure exploration.
  • 从干净的已登录状态开始，或在前置条件中说明初始状态。
  • 每步一个操作。将“打开订单并点击接收”拆分为两步。
  • 表述准确。使用精确的UI标签或API路径：
    POST /orders/wrapper-pieces?query=...
    。
  • 按属性引用数据，而非ID。“处于‘Open’状态且接收工作流已同步的订单”比“订单d4e7-...”更好。
  • 在失败点停止。不要包含失败后的探索操作。

Expected vs. Actual

预期结果与实际结果

  • Both must be observable by a tester, not internal state. "No error is thrown" is weak; "Toast 'Order saved' appears and status = Open" is strong.
  • Quote errors verbatim, including status code, error code, and message.
  • Diff expected and actual. If a field is wrong, state both values.
  • 两者都必须是测试人员可观察到的，而非内部状态。“未抛出错误”表述较弱；“显示‘订单已保存’提示框且状态=Open”表述更明确。
  • 逐字引用错误信息，包括状态码、错误代码和消息。
  • 对比预期与实际。若某个字段值错误，需同时说明预期值和实际值。

Evidence

证据

  • Stack traces → paste inside a fenced code block; Jira renders it as a scrollable 
    {code}
    block.
  • Logs → include timestamp, logger name, level, and correlation id.
  • SQL / query plans → include for performance bugs.
  • Screenshots / video → attach to Jira, reference by filename.
  • Reproducibility rate matters for triage: always vs. intermittent (e.g., "3 of 10 attempts").
  • 堆栈跟踪 → 粘贴到代码块中；Jira会将其渲染为可滚动的
    {code}
    块。
  • 日志 → 包含时间戳、日志记录器名称、日志级别和关联ID。
  • SQL/查询计划 → 针对性能bug需包含此项。
  • 截图/视频 → 附加到Jira工单，并按文件名引用。
  • 复现概率对分类至关重要：总是复现 vs 间歇性复现（例如：“10次尝试中3次复现”）。

Priority & Severity (FOLIO scale)

优先级与严重程度（FOLIO标准）

Use this matrix as a starting point; the triage team may re-assign.
PriorityWhen to use
P1 — CriticalSevere correctness or availability problems: data loss or corruption, security vulnerability, incorrect financial/calculation output, login/authentication broken, whole app or major workflow unusable, blocks release, or affects downstream processes across the system.
P2 — MajorCore workflow broken or produces wrong results, no reasonable workaround, affects many users.
P3 — NormalDefect with a workaround, affects a specific flow or subset of users.
P4 — MinorCosmetic, typo, edge case with low impact.
TBDPriority not yet assessed — acceptable when filing, expect triage.
以此矩阵为参考起点；分类团队可能会重新分配优先级。
优先级使用场景
P1 — 关键严重的正确性或可用性问题：数据丢失或损坏、安全漏洞、财务/计算输出错误、登录/认证功能失效、整个应用或主要工作流无法使用、阻碍发布，或影响系统下游流程。
P2 — 主要核心工作流失效或输出错误结果，无合理的替代方案，影响大量用户。
P3 — 普通存在替代方案的缺陷，影响特定流程或部分用户。
P4 — 次要外观问题、拼写错误、低影响的边缘场景。
TBD优先级尚未评估 —— 提交时可使用该状态，等待分类。

User Interaction Flow

用户交互流程

Before producing the final bug, check whether the user supplied the essentials. If any of the following are missing or ambiguous, ask the user using the question tool (batch related questions in one call):
  1. Target Jira project (e.g., MODORDERS, UIOR, FOLIO). Required to draft summary prefix and determine Jira creation path.
  2. Environment where the bug occurs (snapshot, bugfest, dry-run, local, specific tenant).
  3. Reproducibility (always / intermittent / once-off). Drives triage.
  4. Steps to reproduce if only a symptom was given.
  5. Expected behavior source (spec, ticket, "previous release"). Needed when "expected" is subjective.
  6. Supporting evidence — logs, stack trace, screenshots, HAR, recordings.
  7. Priority suggestion if the user has context on impact.
Do not ask about sections the user can reasonably leave to triage (fix versions, components, labels) unless they volunteer them.
生成最终bug报告前，检查用户是否提供了必要信息。若以下任何一项缺失或不明确，使用提问工具询问用户（将相关问题批量一次性提出）：
  1. 目标Jira项目（例如：MODORDERS、UIOR、FOLIO）。编写摘要前缀和确定Jira创建路径时必填。
  2. bug出现的环境（快照环境、bugfest环境、dry-run环境、本地环境、特定租户）。
  3. 复现概率（总是/间歇性/仅一次）。影响分类决策。
  4. 复现步骤（若用户仅提供了症状）。
  5. 预期行为的参考来源（规格说明、工单、“之前版本的表现”）。当“预期”存在主观性时需要此项。
  6. 支持性证据 —— 日志、堆栈跟踪、截图、HAR文件、录制视频。
  7. 优先级建议（若用户了解影响范围）。
除非用户主动提供，否则不要询问用户可合理留给分类团队处理的部分（修复版本、组件、标签）。

Optional: file the bug in Jira

可选：在Jira中提交bug

After the user approves the draft, offer to create the ticket via 
mcp-atlassian_jira_create_issue
:
  • Use the agreed project key and 
    issue_type: "Bug"
    .
  • Convert the Markdown draft to Jira markup (see references/jira.md).
  • Pass 
    priority
    , 
    labels
    , 
    components
    , and 
    fixVersions
    via 
    additional_fields
    only when the user confirmed them.
  • After creation, return the issue key and URL.
Before creating, search for duplicates with 
mcp-atlassian_jira_search
using keywords from the summary and show the top matches to the user.
用户批准草稿后，可通过
mcp-atlassian_jira_create_issue
创建工单：
  • 使用商定的项目密钥和
    issue_type: "Bug"
    。
  • 将Markdown草稿转换为Jira标记语言（详见references/jira.md）。
  • 仅当用户确认后，才通过
    additional_fields
    传递
    priority
    、
    labels
    、
    components
    和
    fixVersions
    。
  • 创建完成后，返回工单密钥和URL。
创建前，使用
mcp-atlassian_jira_search
搜索重复工单，利用摘要中的关键词查找并向用户展示最匹配的结果。

Best Practices

最佳实践

Do ✓

应做 ✓

  1. One bug per ticket. Split compound defects.
  2. Write preconditions so someone else can reach the starting state.
  3. Quote errors verbatim, including codes and IDs.
  4. State reproducibility rate for intermittent bugs.
  5. Link regression source (the ticket that introduced it) when known.
  6. Search for duplicates before filing.
  1. 每张工单对应一个bug。拆分复合缺陷。
  2. 编写前置条件时，确保他人能达到起始状态。
  3. 逐字引用错误信息，包括代码和ID。
  4. 说明间歇性bug的复现概率。
  5. 已知时链接引入缺陷的回归来源工单。
  6. 提交前搜索重复工单。

Don't ✗

不应做 ✗

  1. Don't hypothesize a root cause in the summary or steps. Put hypotheses in a clearly labelled Additional information note.
  2. Don't mix multiple defects in one ticket.
  3. Don't use vague verbs: "doesn't work", "is broken", "acts weird".
  4. Don't paste secrets (tokens, real user emails, tenant credentials).
  5. Don't include the proposed fix in the bug itself — that belongs in the PR or a linked story.
  6. Don't skip the expected result — "it should work" is not testable.
  1. 不要在摘要或步骤中假设根本原因。将假设放在明确标记为_补充信息_的部分中。
  2. 不要在一张工单中混合多个缺陷。
  3. 不要使用模糊动词：“无法工作”、“已损坏”、“表现异常”。
  4. 不要粘贴敏感信息（令牌、真实用户邮箱、租户凭证）。
  5. 不要在bug报告中包含建议的修复方案 —— 修复方案应放在PR或关联的需求工单中。
  6. 不要省略预期结果 —— “应该正常工作”无法测试。

Quick Reference Checklist

快速参考检查清单

  • Summary identifies area + symptom + trigger
  • Preconditions are independently verifiable
  • Steps are numbered, atomic, and start from a defined state
  • Expected result references a source of truth
  • Actual result includes exact error text / status code
  • Reproducibility rate is stated
  • Environment and module versions are recorded
  • Stack traces / logs / screenshots attached or inlined
  • Workaround documented if one exists
  • No PII, secrets, or real credentials
  • Duplicate search performed before filing
  • One defect per ticket
For section-by-section guidance, see references/section-details.md. For a complete example bug, see references/example.md. For Markdown → Jira markup conversion, see references/jira.md. For common pitfalls with before/after rewrites, see references/pitfalls.md.
  • 摘要明确了区域+症状+触发条件
  • 前置条件可独立验证
  • 步骤编号清晰、原子化，并从明确状态开始
  • 预期结果参考了权威来源
  • 实际结果包含准确的错误文本/状态码
  • 说明了复现概率
  • 记录了环境和模块版本
  • 附加或内联了堆栈跟踪/日志/截图
  • 若存在替代方案则已记录
  • 无个人身份信息（PII）、敏感信息或真实凭证
  • 提交前已搜索重复工单
  • 每张工单对应一个缺陷
如需逐部分详细指南，请查看references/section-details.md。 如需完整的bug报告示例，请查看references/example.md。 如需Markdown转Jira标记语言的方法，请查看references/jira.md。 如需常见的前后改写陷阱，请查看references/pitfalls.md。