writing-upstream-bug-reports

用途：当遇到缺陷、回归、崩溃、Linux/系统问题、软件包或第三方库缺陷，需要撰写结构化上游缺陷报告时使用；不适用于内部 TODO、功能请求、团队内部跟踪的项目问题，或无需提交上游的已知限制。\n\n主要能力：产出以症状为先、便于分诊的自包含报告文件夹，结构为：bug-report-name/ 内含 ISSUE.md（主报告）、SUBMISSION-INSTRUCTIONS.md（提交位置与方式）、attachments/（日志、配置、截图、原始数据），复杂报告可选 README.md。\n\nISSUE.md 分段：标题（H1，症状导向、便于搜索）；组件（项目、包、发行版）；摘要（2-3 句，加粗关键发现）；环境；复现步骤（编号、具体命令）；预期结果；实际结果（精确输出，加粗异常）；临时方案（标明手动每次启动／持久／部分修复）；根因分析（写明确是什么、并排除其他可能）；日志与附件清单；给维护者的具体问题（可选）；相关问题对比表（可选）。SUBMISSION-INSTRUCTIONS.md 覆盖：提交位置（上游与下游地址，优先上游）、各跟踪器提交流程、最少与完整附件集、重新生成附件的命令、后续跟进指引。\n\n证据收集：在复现时收集原始输出而非转述，如服务日志（journalctl -b -u service.service）、系统日志（dmesg、journalctl -b -p err）、配置文件、系统状态（ip addr、ip route、nft list ruleset、free -h）、硬件信息（lscpu、smartctl、uname -a）、应用输出（logcat 等）。多份快照用时间戳命名，优先整份输出重定向到文件。\n\n写作风格：先症状后理论，使用精确命令与输出，加粗关键异常，ISSUE.md 自包含，写给出 30 秒分诊的维护者。常见错误包括把症状埋在第 5 段、只说“不工作”、缺少复现步骤、附件未被引用、混淆上下游、无证据推测、遗漏环境信息。\n\n限制：资料未提供具体项目专属模板或自动化工具；是否收费、适用平台等暂未提供。